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>

.forgejo/workflows/check.yml

@@ -1,102 +0,0 @@
-# Nomarchy CI — eval + lint.
-#
-# Catches the regressions that hurt today:
-#   1. Flake stops evaluating (broken option ref, missing import, etc.).
-#   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).
-#
-# 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
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@main
-        with:
-          # Match the runner's effective channel. Nomarchy itself tracks
-          # nixos-25.11 via flake.nix; the installer-action default is fine.
-          extra-conf: |
-            experimental-features = nix-command flakes
-
-      - name: nix flake check --no-build
-        run: nix flake check --no-build
-
-      - 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

.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

README.md

@@ -84,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). Hit a rebuild error? Check [Troubleshooting](docs/TROUBLESHOOTING.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:

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:
@@ -98,10 +104,12 @@ all_refs=$(grep -rhE 'nomarchy-[a-z0-9]([a-z0-9-]*[a-z0-9])?' \
               -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
@@ -109,6 +117,10 @@ all_refs=$(grep -rhE 'nomarchy-[a-z0-9]([a-z0-9-]*[a-z0-9])?' \
 # 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/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/config/nomarchy-skill/SKILL.md

@@ -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` |
 
@@ -334,16 +334,6 @@ 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).
 
-### Voice dictation (Voxtype)
-
-```bash
-nomarchy-voxtype-install                 # Install Voxtype + AI model (~150MB)
-nomarchy-voxtype-remove                  # Uninstall Voxtype
-nomarchy-voxtype-status                  # Running state (also shown in waybar)
-```
-
-Toggle dictation with `SUPER+CTRL+X` after install.
-
 ### Virtualization
 
 ```bash
@@ -370,8 +360,9 @@ nomarchy-upload-log
 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)
@@ -386,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

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/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-v2.conf
-source = ~/.config/nomarchy/default/hypr/bindings/utilities.conf

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,9 +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

@@ -10,5 +10,6 @@
     ./security.nix
     ./bash.nix
     ./gaming.nix
+    ./accessibility.nix
   ];
 }

core/home/options.nix

@@ -42,7 +42,11 @@ in
     theme = lib.mkOption {
       type = lib.types.str;
       default = schema.home.theme;
-      description = "System theme name.";
+      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,38 +60,84 @@ in
         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 = schema.home.wallpaper;
-      description = "System wallpaper path.";
+      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.";
+      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 = schema.home.hyprland.gaps_in;
-        description = "Inner gaps for Hyprland.";
+        description = "Inner gaps for Hyprland. Driven by the declarative state.";
       };
       gaps_out = lib.mkOption {
         type = lib.types.int;
         default = schema.home.hyprland.gaps_out;
-        description = "Outer gaps for Hyprland.";
+        description = "Outer gaps for Hyprland. Driven by the declarative state.";
       };
       border_size = lib.mkOption {
         type = lib.types.int;
         default = schema.home.hyprland.border_size;
-        description = "Border size for Hyprland.";
+        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 = schema.home.font;
-        description = "System monospace 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 {
@@ -119,14 +169,25 @@ in
     };
 
     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 = {
@@ -139,5 +200,19 @@ in
         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

@@ -2,33 +2,63 @@
 
 # File-based override system for Nomarchy.
 #
-# STATUS: option surface only — the actual override mechanism is NOT yet
-# implemented. The options are kept so configs that already set
-# `nomarchy.overrides.enable = …;` continue to evaluate; setting them has
-# no effect today. Tracked in docs/ROADMAP.md.
+# 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.
 #
-# When implemented, this module should substitute sources in
-# `xdg.configFile.<path>.source` based on the presence of matching files
-# under ~/.config/nomarchy/overrides/.
+# 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
+  cfg = config.nomarchy.overrides;
+in
 {
   options.nomarchy.overrides = {
     enable = lib.mkOption {
       type = lib.types.bool;
       default = true;
       description = ''
-        Reserved for the future file-based override loader. Currently a
-        no-op — setting this has no effect. See docs/ROADMAP.md.
+        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 = {};
+      example = lib.literalExpression ''
+        {
+          "nomarchy/default/hypr/looknfeel.conf" = ./looknfeel.conf;
+          "waybar/style.css" = ./waybar.css;
+        }
+      '';
       description = ''
-        Reserved for the future file-based override loader. Currently
-        unused.
+        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 cfg.enable {
+    xdg.configFile = lib.mapAttrs (_path: src: {
+      source = lib.mkForce src;
+    }) cfg.paths;
+  };
 }

core/home/state.nix

@@ -1,4 +1,4 @@
-{ config, lib, ... }:
+{ config, lib, pkgs, ... }:
 
 let
   nomarchyLib = import ../../lib { inherit lib; };
@@ -12,41 +12,54 @@ let
 
   # 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 state.json-derived value. Without mkDefault, every
-  # option here would resolve at default priority and conflict on
-  # assignment from the user's config.
+  # 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 = lib.mkDefault (togglesState.suspend or schema.home.suspend);
-        screensaver = lib.mkDefault (togglesState.screensaver or schema.home.screensaver);
-        idle = lib.mkDefault (togglesState.idle or schema.home.idle);
-        nightlight = lib.mkDefault (togglesState.nightlight or schema.home.nightlight);
-        waybar = lib.mkDefault (togglesState.waybar or schema.home.waybar);
-      };
-      nightlightTemperature = lib.mkDefault (togglesState.nightlightTemperature or schema.home.nightlightTemperature);
-      theme = lib.mkDefault (togglesState.theme or schema.home.theme);
-      wallpaper = lib.mkDefault (togglesState.wallpaper or schema.home.wallpaper);
-      panelPosition = lib.mkDefault (togglesState.panelPosition or schema.home.panelPosition);
-      hyprland = {
-        gaps_in = lib.mkDefault (togglesState.hyprland.gaps_in or schema.home.hyprland.gaps_in);
-        gaps_out = lib.mkDefault (togglesState.hyprland.gaps_out or schema.home.hyprland.gaps_out);
-        border_size = lib.mkDefault (togglesState.hyprland.border_size or schema.home.hyprland.border_size);
-      };
-      fonts.monospace = lib.mkDefault (togglesState.font or schema.home.font);
-
       # Derived properties from the theme directory
       isLightMode = lib.mkDefault (nomarchyLib.isThemeLightMode {
-        themeName = togglesState.theme or schema.home.theme;
+        themeName = cfg.theme;
         inherit assetsPath;
       });
       iconsTheme = lib.mkDefault (nomarchyLib.getIconsTheme {
-        themeName = togglesState.theme or schema.home.theme;
+        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/default.nix

@@ -9,6 +9,7 @@
     ./nix.nix
     ./scripts.nix
     ./systemd.nix
+    ./session.nix
     ./virtualization.nix
     ./fonts.nix
     ./hardware.nix
@@ -17,6 +18,7 @@
     ./network.nix
     ./impermanence.nix
     ./browser.nix
+    ./file-manager.nix
     # Tier 1 system features (all opt-in via nomarchy.system.*).
     ./snapper.nix
     ./laptop.nix

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/gaming.nix

@@ -1,4 +1,4 @@
-{ config, lib, ... }:
+{ config, lib, pkgs, ... }:
 
 let
   cfg = config.nomarchy.system.gaming;
@@ -16,5 +16,29 @@ in
     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/impermanence.nix

@@ -39,32 +39,64 @@ in
   };
 
   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/${cfg.mainLuksName} /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" = {

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/options.nix

@@ -61,7 +61,10 @@ in
     theme = lib.mkOption {
       type = lib.types.str;
       default = schema.system.theme;
-      description = "Selected 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) ---
@@ -203,14 +206,5 @@ in
         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

@@ -33,6 +33,7 @@ let
     fwupd
     hyprland
     swayosd
+    python3   # nomarchy-haptic-touchpad is a python3 script (Dell XPS service)
   ];
 in
 pkgs.stdenv.mkDerivation {

core/system/scripts/nomarchy-setup-dns

@@ -14,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)
@@ -28,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

@@ -6,13 +6,13 @@ set -e
 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

@@ -6,13 +6,13 @@ set -e
 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-toggle-hybrid-gpu

@@ -9,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

@@ -21,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-tz-select

@@ -7,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-wifi-powersave

@@ -12,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

@@ -10,20 +10,8 @@ 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 state.json-derived value. Without
-  # mkDefault, every state.json-driven option was unoverridable from
-  # Nix — flipping hybridGPU required jq'ing the state file rather
-  # than declaring it in your config.
+  # without colliding with the default values. The Nix options are now the
+  # declarative source of truth.
   config.nomarchy.system = {
-    dns = lib.mkDefault (systemState.dns or schema.system.dns);
-    customDns = lib.mkDefault (systemState.customDns or schema.system.customDns);
-    wifi.powersave = lib.mkDefault (systemState.wifi.powersave or schema.system.wifi.powersave);
-    timezone = lib.mkDefault (systemState.timezone or schema.system.timezone);
-    features = {
-      fingerprint = lib.mkDefault (systemState.features.fingerprint or schema.system.features.fingerprint);
-      fido2 = lib.mkDefault (systemState.features.fido2 or schema.system.features.fido2);
-      hybridGPU = lib.mkDefault (systemState.features.hybridGPU or schema.system.features.hybridGPU);
-    };
-    theme = lib.mkDefault (systemState.theme or schema.system.theme);
   };
 }

core/system/virtualization.nix

@@ -5,16 +5,6 @@ let
   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.

docs/AGENT.md

@@ -64,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)
@@ -77,7 +79,7 @@ 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.
@@ -143,6 +145,11 @@ Steps you should follow for any non-trivial change:
    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
@@ -151,7 +158,7 @@ Steps you should follow for any non-trivial change:
    ```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.
 
@@ -194,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,7 +52,6 @@ _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 |

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
@@ -242,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

@@ -129,10 +129,6 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 `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.
@@ -177,10 +173,18 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 `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".
@@ -243,7 +247,51 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 ### `nomarchy.configOverrides`
 
-`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.*` is a reserved option surface (currently a no-op).
+`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.apps.alacritty.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated Alacritty configuration. The installer enables this by default.
+
+### `nomarchy.apps.btop.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated btop configuration (themed color scheme, vim keys). The installer enables this by default.
+
+### `nomarchy.apps.ghostty.enable`
+
+`bool`, default `false`. Deploys Nomarchy's curated Ghostty configuration.
+
+### `nomarchy.apps.kitty.enable`
+
+`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`
 
@@ -253,9 +301,9 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 `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.vscode.devExtensions`
+### `nomarchy.accessibility.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.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`
 
@@ -267,11 +315,22 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 ### `nomarchy.overrides.enable`
 
-`bool`, default `true`. **Reserved — currently a no-op.** Intended to gate a future file-based override loader (drop a file under `~/.config/nomarchy/overrides/`, have it substitute the bundled default for that path). The option exists so configs that set it don't fail to evaluate; setting it has no effect today. Use `nomarchy.configOverrides` for bulk redirection, or set `xdg.configFile.<path>.source` directly in your `home.nix` for per-file overrides — Nomarchy's defaults use `lib.mkDefault` and yield to higher-priority assignments. Tracked in `docs/ROADMAP.md`.
+`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 `{}`. **Reserved — currently unused.** Will be populated by the future override loader.
+`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.
 
 ---
 
@@ -323,6 +382,6 @@ The same pattern works for any file Nomarchy deploys via `xdg.configFile.<path>.
 - `core/system/hardware.nix` — `nomarchy.hardware.*`
 - `core/system/impermanence.nix` — `impermanence.enable`
 - `core/home/options.nix` — most home-side `nomarchy.*` options
-- `core/home/overrides.nix` — `nomarchy.overrides.*` (reserved; currently no-op)
+- `core/home/overrides.nix` — `nomarchy.overrides.*`
 - `themes/engine/loader.nix` — `nomarchy.themeLoader.*`
 - `features/apps/vscode.nix` — `nomarchy.vscode.*`

docs/ROADMAP.md

@@ -19,31 +19,23 @@ Guardrails (apply when adding anything):
 
 ### Now (ready to pick up)
 
-- **Full QA audit of shipped features.** Walk every feature/component end-to-end on a real install, fix what's small, log what's not. Runs as per-component PR sweeps — methodology in [Pillar 8](#8-pillar-qa-audit--features--components).
-- **Installer: "What's installed?" summary on first boot.** Surface what the installer actually wrote (theme, font, profiles, drives, form factor) from `state.json` + `nomarchy-system-scripts` introspection so the user can verify before they start customising. Detail in [Pillar 4](#4-pillar-installer).
-- **Installer: optional non-LUKS branch.** Let users explicitly opt out of FDE during install. Detail in [Pillar 4](#4-pillar-installer).
+_(empty — all entries shipped or moved to Later)_
 
 ### Next (bigger lifts that build on Now)
 
-- **Accessibility — home-side companion.** Hyprland-side bits the system preset can't reach: slower `input.repeat_rate` / `repeat_delay` defaults, `SUPER+ALT+S` keybinding to launch Orca, and a high-contrast palette under `themes/palettes/`. Gated on a new `nomarchy.accessibility.enable` mirror of the system option.
-- **Gaming — declarative flathub remote.** `services.flatpak.enable` doesn't ship a declarative remote API in nixpkgs. Either add the `flatpak-managed-install` overlay, write a one-shot systemd unit that runs `flatpak remote-add --if-not-exists flathub …`, or surface the manual step in `nomarchy-welcome`.
-- **Plymouth theme variants per palette.** Currently one Plymouth theme; could template per-palette so the boot splash matches the active theme.
-- **Implement `nomarchy.overrides.*` file-based override loader.** The option surface is declared in `core/home/overrides.nix` but the loader doesn't exist — files dropped under `~/.config/nomarchy/overrides/` are ignored. Spec: when `overrides.enable = true`, for each `xdg.configFile.<path>` Nomarchy deploys with `lib.mkDefault`, check whether `~/.config/nomarchy/overrides/<path>` exists at build time; if so, use it as the source. Requires deciding whether discovery happens at activation time (cheap, but rebuild-required to pick up new files) or via a populated `paths` attrset (Nix-side, evaluated once per rebuild). Until shipped, document the per-file workaround (`xdg.configFile.<path>.source = ./mine`) in OPTIONS.md.
-
 ### 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 `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.
-- **Consolidate palette imports in `flake.nix` via `nomarchyLib`.** `flake.nix:79-80` re-imports `./themes/palettes` and recomputes `themeNames` even though `lib/default.nix` already exports both. Two computations, same result today — drift risk tomorrow. Import `nomarchyLib = import ./lib { inherit lib; }` once and use `nomarchyLib.{palettes,themeNames}` to make `lib/default.nix` the single source of truth for the theme list.
-- **Decide what to do about `features/apps/chromium/Default/Preferences`.** The module deploys a static 204-byte `Default/Preferences` (setting `extensions.theme.use_system = false`, `browser.theme.color_scheme = 2`) into chromium's mutable profile directory via Home Manager symlink. Chromium expects to write that file at runtime, so either the symlink is silently replaced on first save (losing the static defaults) or the write fails silently. The real chromium theming work happens via managed policies in `core/system/browser.nix`. Probably the user-profile deployment should be removed; needs someone with chromium-internals knowledge to confirm before deletion.
-- **`themes/templates/*.tpl` — decide what these are for.** Eleven mustache-style templates (`alacritty.toml.tpl`, `btop.theme.tpl`, `kitty.conf.tpl`, etc.) are deployed to `~/.local/share/nomarchy/templates/` via `themes/engine/files.nix`, but no script in the tree consumes them. Likely vestigial from a pre-stylix templating system. Either delete the directory + the `xdg.dataFile` deployment, or document them as user-reference assets and explain how to use them.
-- **Move `programs.uwsm` Hyprland session out of `core/system/virtualization.nix`.** Session-manager config is wired in the virtualization module by historical accident — it's loaded unconditionally on every install and has nothing to do with libvirt/docker. Move to a dedicated `core/system/session.nix` (or fold into the Hyprland feature module) so the location matches the responsibility.
+- **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,8 +72,7 @@ Each PR description should reference the row(s) in `docs/SCRIPTS.md` it closes,
 
 ## 4. Pillar: Installer
 
-- "What's installed?" summary screen on boot of a freshly-installed system, sourced from `state.json` + `nomarchy-system-scripts` introspection (Now).
-- Optional non-LUKS branch in the installer for users who explicitly opt out of FDE (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).
 - `disko-golden.nix` variants for software-RAID and BTRFS-pool-as-root (Shipped).
 - Pre-flight resume polish (Shipped).
@@ -143,7 +134,38 @@ Per-PR deliverable:
 
 Pillar is **done** when every component has a closed `wave/qa-<component>` PR and the roadmap captures every deferred finding.
 
-## 9. Process notes
+## 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.
@@ -155,6 +177,64 @@ Pillar is **done** when every component has a closed `wave/qa-<component>` PR an
 
 (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.

docs/SCRIPTS.md

@@ -24,7 +24,7 @@ Phase B (per-batch PRs) refines those into `port-from-omarchy`,
 - `delete-dead` — Phase B verdict: remove and update callers.
 - `stub-with-notify` — Phase B verdict: temporary `notify-send` stub.
 
-## Scripts (159)
+## Scripts (151)
 
 | Script | Location | Callers | Status | Notes |
 | --- | --- | --- | --- | --- |
@@ -40,31 +40,29 @@ Phase B (per-batch PRs) refines those into `port-from-omarchy`,
 | `nomarchy-build-iso` | `features/scripts/utils` | README.md | `kept` |  |
 | `nomarchy-build-live-iso` | `features/scripts/utils` | README.md | `kept` |  |
 | `nomarchy-cmd-audio-switch` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/media.conf | `kept` |  |
-| `nomarchy-cmd-present` | `features/scripts/utils` | core/home/config/nomarchy/hooks/battery-low.sample,features/scripts/utils/nomarchy-launch-editor, +4 more | `kept` |  |
+| `nomarchy-cmd-present` | `features/scripts/utils` | core/home/config/nomarchy/hooks/battery-low.sample,features/scripts/utils/nomarchy-launch-editor, +2 more | `kept` |  |
 | `nomarchy-cmd-screenrecord` | `features/scripts/utils` | features/desktop/waybar/config/config.jsonc,features/desktop/waybar/themes/summer-night/config.jsonc, +1 more | `kept` |  |
 | `nomarchy-cmd-screensaver` | `features/scripts/utils` | features/scripts/utils/nomarchy-launch-screensaver | `kept` |  |
-| `nomarchy-cmd-screenshot` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy-skill/SKILL.md, +1 more | `kept` |  |
+| `nomarchy-cmd-screenshot` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +1 more | `kept` |  |
 | `nomarchy-cmd-share` | `features/scripts/utils` | features/scripts/utils/nomarchy-menu | `kept` |  |
-| `nomarchy-cmd-terminal-cwd` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/plain-bindings.conf,features/desktop/hyprland/config/bindings.conf | `kept` |  |
+| `nomarchy-cmd-terminal-cwd` | `features/scripts/utils` | features/desktop/hyprland/config/bindings.conf | `kept` |  |
 | `nomarchy-debug` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
-| `nomarchy-docs-keybindings` | `features/scripts/utils` | bin/utils/nomarchy-docs-keybindings | `kept` |  |
-| `nomarchy-docs-scripts` | `features/scripts/utils` | bin/utils/nomarchy-docs-scripts | `kept` |  |
 | `nomarchy-drive-info` | `features/scripts/utils` | features/scripts/utils/nomarchy-drive-select | `kept` |  |
 | `nomarchy-drive-select` | `features/scripts/utils` | features/scripts/utils/nomarchy-drive-info,features/scripts/utils/nomarchy-drive-set-password | `kept` |  |
 | `nomarchy-drive-set-password` | `features/scripts/utils` | features/scripts/utils/nomarchy-drive-select,features/scripts/utils/nomarchy-menu | `kept` |  |
-| `nomarchy-env-update` | `core/system/scripts` | core/home/bash.nix,core/system/scripts.nix, +7 more | `kept` |  |
+| `nomarchy-env-update` | `features/scripts/utils` | core/home/bash.nix,core/home/options.nix, +8 more | `kept` |  |
 | `nomarchy-font` | `features/scripts/utils` | bin/utils/nomarchy-docs-scripts,core/home/config/nomarchy-skill/SKILL.md, +6 more | `kept` |  |
 | `nomarchy-font-current` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-font-list` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-font, +2 more | `kept` |  |
 | `nomarchy-font-set` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-font, +4 more | `kept` |  |
-| `nomarchy-haptic-touchpad` | `core/system/scripts` | core/system/hardware.nix | `kept` |  |
+| `nomarchy-haptic-touchpad` | `core/system/scripts` | core/system/hardware.nix,core/system/scripts-derivation.nix | `kept` |  |
 | `nomarchy-hibernation-available` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-hibernation-remove` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-hibernation-setup` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
-| `nomarchy-hook` | `features/scripts/utils` | core/system/scripts/nomarchy-battery-monitor,themes/engine/scripts/nomarchy-font-set, +1 more | `kept` |  |
+| `nomarchy-hook` | `features/scripts/utils` | core/system/scripts/nomarchy-battery-monitor,features/scripts/utils/nomarchy-env-update, +3 more | `kept` |  |
 | `nomarchy-hw-asus-rog` | `core/system/scripts` | features/scripts/utils/nomarchy-on-boot | `kept` |  |
 | `nomarchy-hw-match` | `core/system/scripts` | features/scripts/utils/nomarchy-on-boot | `kept` |  |
-| `nomarchy-hw-vulkan` | `core/system/scripts` | features/scripts/utils/nomarchy-voxtype-install | `kept` |  |
+| `nomarchy-hw-vulkan` | `core/system/scripts` | — | `unused?` |  |
 | `nomarchy-hyprland-active-window-transparency-toggle` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf | `kept` |  |
 | `nomarchy-hyprland-monitor-scaling-cycle` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/tiling-v2.conf,features/scripts/utils/nomarchy-menu, +1 more | `kept` |  |
 | `nomarchy-hyprland-window-close-all` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/tiling-v2.conf,core/system/scripts/nomarchy-system-logout, +2 more | `kept` |  |
@@ -72,36 +70,34 @@ Phase B (per-batch PRs) refines those into `port-from-omarchy`,
 | `nomarchy-hyprland-window-pop` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/tiling-v2.conf | `kept` |  |
 | `nomarchy-hyprland-window-single-square-aspect-toggle` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-hyprland-workspace-layout-toggle` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/tiling-v2.conf,features/scripts/utils/nomarchy-menu | `kept` |  |
-| `nomarchy-install` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,hosts/nomarchy-installer.nix, +2 more | `kept` |  |
+| `nomarchy-install` | `features/scripts/utils` | README.md,core/home/config/nomarchy-skill/SKILL.md, +2 more | `kept` |  |
 | `nomarchy-install-docker-dbs` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
+| `nomarchy-installed-summary` | `features/scripts/utils` | core/home/state.nix,features/scripts/utils/nomarchy-welcome | `kept` |  |
 | `nomarchy-launch-about` | `features/scripts/utils` | features/scripts/utils/nomarchy-menu | `kept` |  |
-| `nomarchy-launch-audio` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/desktop/waybar/config/config.jsonc, +2 more | `kept` |  |
+| `nomarchy-launch-audio` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/desktop/waybar/config/config.jsonc, +3 more | `kept` |  |
 | `nomarchy-launch-bluetooth` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/desktop/waybar/config/config.jsonc, +1 more | `kept` |  |
-| `nomarchy-launch-browser` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/plain-bindings.conf,core/home/config/nomarchy-skill/SKILL.md, +1 more | `kept` |  |
-| `nomarchy-launch-editor` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/plain-bindings.conf,features/desktop/hyprland/config/bindings.conf, +2 more | `kept` |  |
+| `nomarchy-launch-browser` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/desktop/hyprland/config/bindings.conf | `kept` |  |
+| `nomarchy-launch-editor` | `features/scripts/utils` | features/desktop/hyprland/config/bindings.conf,features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-launch-floating-terminal-with-presentation` | `features/scripts/utils` | core/home/config/nomarchy/default/mako/core.ini,features/desktop/waybar/config/config.jsonc, +3 more | `kept` |  |
-| `nomarchy-launch-or-focus` | `features/scripts/utils` | core/home/config/nomarchy/extensions/menu.sh,features/desktop/hyprland/config/bindings.conf, +6 more | `kept` |  |
-| `nomarchy-launch-or-focus-tui` | `features/scripts/utils` | core/home/config/nomarchy/extensions/menu.sh,features/desktop/waybar/config/config.jsonc, +3 more | `kept` |  |
+| `nomarchy-launch-or-focus` | `features/scripts/utils` | core/home/config/nomarchy/extensions/menu.sh,features/desktop/hyprland/config/bindings.conf, +8 more | `kept` |  |
+| `nomarchy-launch-or-focus-tui` | `features/scripts/utils` | core/home/config/nomarchy/extensions/menu.sh,features/desktop/waybar/config/config.jsonc, +5 more | `kept` |  |
 | `nomarchy-launch-or-focus-webapp` | `features/scripts/utils` | features/desktop/hyprland/config/bindings.conf | `kept` |  |
 | `nomarchy-launch-screensaver` | `features/scripts/utils` | features/desktop/idle.nix,features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-launch-tui` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/desktop/hyprland/config/bindings.conf, +2 more | `kept` |  |
 | `nomarchy-launch-walker` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/clipboard.conf,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +4 more | `kept` |  |
-| `nomarchy-launch-webapp` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/plain-bindings.conf,features/desktop/hyprland/config/bindings.conf, +5 more | `kept` |  |
-| `nomarchy-launch-wifi` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy/default/mako/core.ini, +4 more | `kept` |  |
-| `nomarchy-lock-screen` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy/extensions/menu.sh, +3 more | `kept` |  |
-| `nomarchy-manual` | `features/scripts/utils` | core/branding/about.txt,features/scripts/utils/nomarchy-menu, +1 more | `kept` |  |
-| `nomarchy-menu` | `features/scripts/utils` | bin/utils/nomarchy-docs-scripts,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +10 more | `kept` |  |
-| `nomarchy-menu-keybindings` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy/default/mako/core.ini, +2 more | `kept` |  |
+| `nomarchy-launch-webapp` | `features/scripts/utils` | features/desktop/hyprland/config/bindings.conf,features/scripts/utils/nomarchy-launch-or-focus-webapp, +4 more | `kept` |  |
+| `nomarchy-launch-wifi` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy/default/mako/core.ini, +5 more | `kept` |  |
+| `nomarchy-lock-screen` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +3 more | `kept` |  |
+| `nomarchy-manual` | `features/scripts/utils` | core/branding/about.txt,core/home/config/nomarchy/hooks/post-install.sample, +2 more | `kept` |  |
+| `nomarchy-menu` | `features/scripts/utils` | README.md,bin/utils/nomarchy-docs-scripts, +9 more | `kept` |  |
+| `nomarchy-menu-keybindings` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +2 more | `kept` |  |
 | `nomarchy-notification-dismiss` | `features/scripts/utils` | core/home/config/nomarchy/default/mako/core.ini | `kept` |  |
 | `nomarchy-on-boot` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/autostart.conf | `kept` |  |
-| `nomarchy-pkg-add` | `core/system/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-pkg-install, +2 more | `kept` |  |
-| `nomarchy-pkg-aur-add` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
-| `nomarchy-pkg-drop` | `features/scripts/utils` | features/scripts/utils/nomarchy-voxtype-remove | `kept` |  |
-| `nomarchy-pkg-install` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
-| `nomarchy-pkg-remove` | `core/system/scripts` | features/scripts/utils/nomarchy-pkg-drop | `kept` |  |
+| `nomarchy-pkg-add` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-windows-vm | `kept` |  |
+| `nomarchy-pkg-remove` | `features/scripts/utils` | — | `unused?` |  |
 | `nomarchy-powerprofiles-list` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
-| `nomarchy-preflight-migration` | `core/system/scripts` | core/system/scripts/nomarchy-env-update | `kept` |  |
-| `nomarchy-refresh-config` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-refresh-fastfetch | `kept` |  |
+| `nomarchy-preflight-migration` | `features/scripts/utils` | features/scripts/utils/nomarchy-env-update | `kept` |  |
+| `nomarchy-refresh-config` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,core/home/configs.nix, +1 more | `kept` |  |
 | `nomarchy-refresh-fastfetch` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-refresh-hyprland` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-refresh-waybar` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
@@ -117,74 +113,70 @@ Phase B (per-batch PRs) refines those into `port-from-omarchy`,
 | `nomarchy-restart-terminal` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-restart-trackpad` | `core/system/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-restart-walker` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-menu, +1 more | `kept` |  |
-| `nomarchy-restart-waybar` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-menu, +4 more | `kept` |  |
+| `nomarchy-restart-waybar` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-menu, +2 more | `kept` |  |
 | `nomarchy-restart-wifi` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
-| `nomarchy-restart-xcompose` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
+| `nomarchy-restart-xcompose` | `core/system/scripts` | — | `unused?` |  |
 | `nomarchy-setup-dns` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-setup-fido2` | `core/system/scripts` | features/scripts/utils/nomarchy-menu,installer/install.sh | `kept` |  |
 | `nomarchy-setup-fingerprint` | `core/system/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-show-done` | `themes/engine/scripts` | features/scripts/utils/nomarchy-launch-floating-terminal-with-presentation | `kept` |  |
 | `nomarchy-show-logo` | `themes/engine/scripts` | features/scripts/utils/nomarchy-launch-floating-terminal-with-presentation | `kept` |  |
 | `nomarchy-skill` | `features/scripts/utils` | core/home/configs.nix | `kept` |  |
-| `nomarchy-state` | `features/scripts/utils` | core/system/scripts/nomarchy-system-reboot,core/system/scripts/nomarchy-system-shutdown, +2 more | `kept` |  |
-| `nomarchy-state-write` | `features/scripts/utils` | features/scripts/utils/nomarchy-welcome | `kept` |  |
+| `nomarchy-state` | `features/scripts/utils` | core/system/scripts/nomarchy-system-reboot,core/system/scripts/nomarchy-system-shutdown, +14 more | `kept` |  |
+| `nomarchy-state-write` | `features/scripts/utils` | core/system/scripts/nomarchy-toggle-idle,features/scripts/utils/nomarchy-hyprland-monitor-scaling-cycle, +9 more | `kept` |  |
 | `nomarchy-sudo-passwordless-toggle` | `core/system/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-sudo-reset` | `core/system/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-swayosd-brightness` | `core/system/scripts` | core/system/scripts/nomarchy-brightness-display,core/system/scripts/nomarchy-brightness-display-apple | `kept` |  |
 | `nomarchy-swayosd-kbd-brightness` | `core/system/scripts` | core/system/scripts/nomarchy-brightness-keyboard | `kept` |  |
-| `nomarchy-sync` | `features/scripts/utils` | features/scripts/utils/nomarchy-backup,README.md | `kept` |  |
+| `nomarchy-sync` | `features/scripts/utils` | README.md,features/scripts/utils/nomarchy-backup, +1 more | `kept` |  |
+| `nomarchy-sync-nix-state` | `features/scripts/utils` | features/scripts/utils/nomarchy-state-write | `kept` |  |
+| `nomarchy-sys-update` | `features/scripts/utils` | core/home/bash.nix,core/system/scripts/nomarchy-setup-dns, +6 more | `kept` |  |
 | `nomarchy-system-logout` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-system-reboot` | `core/system/scripts` | core/home/config/nomarchy-skill/SKILL.md,core/system/scripts/nomarchy-hibernation-setup, +2 more | `kept` |  |
-| `nomarchy-system-shutdown` | `core/system/scripts` | core/home/config/nomarchy/extensions/menu.sh,core/home/config/nomarchy-skill/SKILL.md, +1 more | `kept` |  |
-| `nomarchy-sys-update` | `features/scripts/utils` | core/home/bash.nix,core/system/scripts/nomarchy-setup-dns, +5 more | `kept` |  |
-| `nomarchy-test-installer` | `features/scripts/utils` | features/scripts/utils/nomarchy-test-vm,README.md | `kept` |  |
+| `nomarchy-system-shutdown` | `core/system/scripts` | core/home/config/nomarchy-skill/SKILL.md,core/home/config/nomarchy/extensions/menu.sh, +1 more | `kept` |  |
+| `nomarchy-test-installer` | `features/scripts/utils` | README.md,features/scripts/utils/nomarchy-test-vm | `kept` |  |
 | `nomarchy-test-live-iso` | `features/scripts/utils` | hosts/nomarchy-live.nix | `kept` |  |
 | `nomarchy-test-vm` | `features/scripts/utils` | features/scripts/utils/nomarchy-test-live-iso | `kept` |  |
-| `nomarchy-theme` | `features/scripts/utils` | bin/utils/nomarchy-docs-scripts,core/home/config/nomarchy/default/elephant/nomarchy_background_selector.lua, +17 more | `kept` |  |
+| `nomarchy-theme` | `features/scripts/utils` | README.md,bin/utils/nomarchy-docs-scripts, +17 more | `kept` |  |
 | `nomarchy-theme-bg-install` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
-| `nomarchy-theme-bg-next` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-wallpaper, +1 more | `kept` |  |
-| `nomarchy-theme-bg-set` | `themes/engine/scripts` | core/home/config/nomarchy/default/elephant/nomarchy_background_selector.lua,features/scripts/utils/nomarchy-wallpaper | `kept` |  |
+| `nomarchy-theme-bg-next` | `themes/engine/scripts` | README.md,core/home/config/nomarchy-skill/SKILL.md, +1 more | `kept` |  |
+| `nomarchy-theme-bg-set` | `themes/engine/scripts` | features/apps/elephant/config/menus/nomarchy_background_selector.lua,features/scripts/utils/nomarchy-wallpaper | `kept` |  |
 | `nomarchy-theme-current` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,themes/engine/scripts/nomarchy-theme-next | `kept` |  |
 | `nomarchy-theme-install` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-theme-list` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-theme, +2 more | `kept` |  |
 | `nomarchy-theme-next` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-theme-refresh` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-theme-remove` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
-| `nomarchy-theme-set` | `themes/engine/scripts` | core/home/config/nomarchy/default/elephant/nomarchy_themes.lua,core/home/config/nomarchy-skill/SKILL.md, +9 more | `kept` |  |
+| `nomarchy-theme-set` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/apps/elephant/config/menus/nomarchy_themes.lua, +9 more | `kept` |  |
 | `nomarchy-theme-set-keyboard` | `themes/engine/scripts` | features/scripts/utils/nomarchy-on-boot | `kept` |  |
 | `nomarchy-theme-set-keyboard-asus-rog` | `themes/engine/scripts` | features/scripts/utils/nomarchy-on-boot,themes/engine/scripts/nomarchy-theme-set-keyboard | `kept` |  |
 | `nomarchy-theme-set-keyboard-f16` | `themes/engine/scripts` | features/scripts/utils/nomarchy-on-boot,themes/engine/scripts/nomarchy-theme-set-keyboard | `kept` |  |
 | `nomarchy-theme-set-obsidian` | `themes/engine/scripts` | themes/engine/scripts/nomarchy-theme-set | `kept` |  |
 | `nomarchy-theme-set-templates` | `themes/engine/scripts` | themes/engine/scripts/nomarchy-theme-set | `kept` |  |
-| `nomarchy-themes-prebuild` | `themes/engine/scripts` | installer/install.sh | `kept` |  |
 | `nomarchy-theme-update` | `themes/engine/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
+| `nomarchy-themes-prebuild` | `themes/engine/scripts` | installer/install.sh | `kept` |  |
 | `nomarchy-toggle-hybrid-gpu` | `core/system/scripts` | features/scripts/utils/nomarchy-menu,features/scripts/utils/nomarchy-sys-update, +1 more | `kept` |  |
 | `nomarchy-toggle-idle` | `core/system/scripts` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/desktop/waybar/config/config.jsonc, +2 more | `kept` |  |
-| `nomarchy-toggle-nightlight` | `themes/engine/scripts` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy-skill/SKILL.md, +1 more | `kept` |  |
+| `nomarchy-toggle-nightlight` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +2 more | `kept` |  |
 | `nomarchy-toggle-notification-silencing` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/desktop/waybar/config/config.jsonc, +1 more | `kept` |  |
 | `nomarchy-toggle-screensaver` | `features/scripts/utils` | features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-toggle-suspend` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
-| `nomarchy-toggle-waybar` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy-skill/SKILL.md, +1 more | `kept` |  |
+| `nomarchy-toggle-waybar` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +1 more | `kept` |  |
 | `nomarchy-tui-install` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-tui-remove-all | `kept` |  |
 | `nomarchy-tui-remove` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-tui-remove-all` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-tz-select` | `core/system/scripts` | features/desktop/waybar/config/config.jsonc,features/scripts/utils/nomarchy-menu, +2 more | `kept` |  |
-| `nomarchy-update` | `core/system/scripts` | core/home/config/nomarchy/default/mako/core.ini,core/home/config/nomarchy-skill/SKILL.md, +4 more | `kept` |  |
-| `nomarchy-update-available` | `features/scripts/utils` | features/desktop/waybar/config/config.jsonc,features/desktop/waybar/themes/summer-night/config.jsonc | `kept` |  |
+| `nomarchy-update` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,core/home/config/nomarchy/default/mako/core.ini, +5 more | `kept` |  |
+| `nomarchy-update-available` | `features/scripts/utils` | features/desktop/waybar/config/config.jsonc,features/desktop/waybar/themes/summer-day/config.jsonc, +1 more | `kept` |  |
 | `nomarchy-update-firmware` | `features/scripts/utils` | features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-update-time` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-upload-log` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-debug | `kept` |  |
-| `nomarchy-version` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-debug | `kept` |  |
-| `nomarchy-voxtype-config` | `features/scripts/utils` | features/desktop/waybar/config/config.jsonc,features/desktop/waybar/themes/summer-night/config.jsonc | `kept` |  |
-| `nomarchy-voxtype-install` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
-| `nomarchy-voxtype-model` | `features/scripts/utils` | features/desktop/waybar/config/config.jsonc,features/desktop/waybar/themes/summer-night/config.jsonc | `kept` |  |
-| `nomarchy-voxtype-remove` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
-| `nomarchy-voxtype-status` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/desktop/waybar/config/config.jsonc, +1 more | `kept` |  |
-| `nomarchy-wallpaper` | `features/scripts/utils` | bin/utils/nomarchy-docs-scripts,core/home/config/nomarchy/default/hypr/autostart.conf, +2 more | `kept` |  |
+| `nomarchy-version` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-debug, +1 more | `kept` |  |
+| `nomarchy-wallpaper` | `features/scripts/utils` | bin/utils/nomarchy-docs-scripts,core/home/config/nomarchy/default/hypr/autostart.conf, +3 more | `kept` |  |
 | `nomarchy-webapp-install` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-webapp-remove-all | `kept` |  |
 | `nomarchy-webapp-remove` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-webapp-remove-all` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
-| `nomarchy-welcome` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/autostart.conf | `kept` |  |
+| `nomarchy-welcome` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/autostart.conf,core/home/config/nomarchy/hooks/post-install.sample, +2 more | `kept` |  |
 | `nomarchy-wifi-powersave` | `core/system/scripts` | features/scripts/utils/nomarchy-sys-update,installer/install.sh | `kept` |  |
 | `nomarchy-windows-vm` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 
@@ -202,7 +194,7 @@ Walked from `features/scripts/utils/nomarchy-menu`. Each `case` arm in a `show_*
 | Submenu | Entry | Calls | Status |
 | --- | --- | --- | --- |
 | `show_learn_menu` | Keybindings | `nomarchy-menu-keybindings` | `kept` |
-| `show_learn_menu` | Nomarchy | `nomarchy-launch-webapp` | `kept` |
+| `show_learn_menu` | Nomarchy | `nomarchy-manual` | `kept` |
 | `show_learn_menu` | Hyprland | `nomarchy-launch-webapp` | `kept` |
 | `show_learn_menu` | Arch | `nomarchy-launch-webapp` | `kept` |
 | `show_learn_menu` | Bash | `nomarchy-launch-webapp` | `kept` |
@@ -241,19 +233,8 @@ Walked from `features/scripts/utils/nomarchy-menu`. Each `case` arm in a `show_*
 | `show_setup_menu` | Input | `_(inline)_` | `kept` |
 | `show_setup_menu` | DNS | `nomarchy-setup-dns` | `kept` |
 | `show_setup_menu` | Security | `_(inline)_` | `kept` |
-| `show_setup_menu` | Config | `_(inline)_` | `kept` |
 | `show_setup_security_menu` | Fingerprint | `nomarchy-setup-fingerprint` | `kept` |
 | `show_setup_security_menu` | Fido2 | `nomarchy-setup-fido2` | `kept` |
-| `show_setup_config_menu` | Defaults | `_(inline)_` | `kept` |
-| `show_setup_config_menu` | Hyprland | `_(inline)_` | `kept` |
-| `show_setup_config_menu` | Hypridle | `nomarchy-restart-hypridle` | `kept` |
-| `show_setup_config_menu` | Hyprlock | `_(inline)_` | `kept` |
-| `show_setup_config_menu` | Hyprsunset | `nomarchy-restart-hyprsunset` | `kept` |
-| `show_setup_config_menu` | Swayosd | `nomarchy-restart-swayosd` | `kept` |
-| `show_setup_config_menu` | Walker | `nomarchy-restart-walker` | `kept` |
-| `show_setup_config_menu` | Waybar | `nomarchy-restart-waybar` | `kept` |
-| `show_setup_config_menu` | XCompose | `nomarchy-restart-xcompose` | `kept` |
-| `show_setup_config_menu` | Overrides | `_(inline)_` | `kept` |
 | `show_update_menu` | Nomarchy | `nomarchy-update` | `kept` |
 | `show_update_menu` | Themes | `nomarchy-theme-update` | `kept` |
 | `show_update_menu` | Process | `_(inline)_` | `kept` |

docs/STRUCTURE.md

@@ -20,7 +20,10 @@ Nomarchy is a NixOS-based distribution characterized by its **Modular Merging Ar
 - **Downstream:** A user's installation (typically in `/etc/nixos/`) imports the Upstream flake. The user layers their own `system.nix` and `home.nix` on top, overriding or extending the Upstream settings using native NixOS `lib.mkDefault` and `lib.mkForce` patterns.
 
 ### Hybrid Declarative State
-While the system is defined declaratively, Nomarchy uses a small, local state file (`~/.config/nomarchy/state.json`) to manage user preferences like the active theme, fonts, and feature toggles. This allows for instant UI feedback (via the `env-update` script) without requiring a full system rebuild for every cosmetic change.
+Nomarchy balances the ease of a GUI with the power of declarative configuration.
+- **Runtime Discovery:** Local state files (`~/.config/nomarchy/state.json` and `/etc/nixos/state.json`) handle personal choices like theme, font, and UI toggles. Changes made via the Theme Picker or Welcome Wizard update these files and provide instant visual feedback (via the `env-update` script).
+- **Declarative Persistence:** To ensure these choices are permanent and reproducible, the `nomarchy-state-sync-nix` script automatically mirrors the home-side configuration into `/etc/nixos/nomarchy-state.nix`. This file is imported by the user's `home.nix`.
+- **Solidification:** When you run `nomarchy-env-update`, your current runtime state is "solidified" into the Nix configuration, preventing your settings from reverting to defaults during the next full system rebuild.
 
 ---
 
@@ -44,7 +47,7 @@ While the system is defined declaratively, Nomarchy uses a small, local state fi
   - **`SCRIPTS.md`**: Auto-generated `nomarchy-*` script audit.
   - **`TROUBLESHOOTING.md`**: Common rebuild errors and fixes.
   - **`creating-themes.md`**: Theme palette authoring guide.
-- **`.forgejo/workflows/`**: Forgejo Actions CI. Runs `nix flake check --no-build`, lints every `nomarchy-*` bash script with `bash -n` + `shellcheck --severity=error`, and verifies `docs/SCRIPTS.md` is up to date on every push to `main` and every PR. To activate: enable Actions on the repo in Forgejo and register a `forgejo-runner` (any Docker-capable Linux host works; the workflow uses `ubuntu-latest` and installs Nix itself).
+- **`.gitea/workflows/`**: Gitea/Forgejo Actions CI (the `.gitea/` path is scanned by both Gitea and Forgejo; `.forgejo/` is *not* scanned by Gitea). Runs `nix flake check --no-build`, the opt-in toggle eval matrix (`bin/utils/nomarchy-eval-matrix`), lints every `nomarchy-*` bash script with `bash -n` + `shellcheck --severity=error`, and verifies `docs/SCRIPTS.md` is up to date on every push to `main` and every PR. To activate: enable Actions on the repo and register an `act_runner` (any Docker-capable Linux host works — including the Gitea server itself; the workflow uses `ubuntu-latest` and installs Nix itself).
 - **`.githooks/`**: Optional per-clone git hooks (`pre-commit` lints changed scripts and regenerates `docs/SCRIPTS.md`). Enable with `git config core.hooksPath .githooks`. CI enforces the same invariants tree-wide.
 
 ---

docs/TROUBLESHOOTING.md

@@ -97,7 +97,7 @@ If churn continues, you have a config under `~/.config/<app>/` that home-manager
 error: The path '/persist' does not exist
 ```
 
-**Cause:** Impermanence requires (a) a `/persist` mountpoint that survives the boot wipe, and (b) every directory you want to keep must be in the persistence list. Nomarchy persists the basics in `core/system/impermanence.nix:46-72` (NetworkManager, Bluetooth, fprint, SSH host keys, the user's `.ssh` / `.gnupg` / Documents / Downloads / Pictures / Videos / Projects). Anything else you care about — Steam library, Flatpak data, custom dotfiles — must be added.
+**Cause:** Impermanence requires (a) a `/persist` mountpoint that survives the boot wipe, and (b) every directory you want to keep must be in the persistence list. Nomarchy persists the basics in `core/system/impermanence.nix:91-120` (NetworkManager, Bluetooth, fprint, SSH host keys, the user's `.ssh` / `.gnupg` / Documents / Downloads / Pictures / Videos / Projects). Anything else you care about — Steam library, Flatpak data, custom dotfiles — must be added.
 
 **Fix:** Make sure `/persist` is mounted (check `mount | grep persist`). Then add the missing path in your `system.nix`:
 

docs/WORKING-ON-NOMARCHY.md

@@ -0,0 +1,210 @@
+# Working on Nomarchy — a practical orientation
+
+This is the "I just want to change something without getting lost" guide. It is
+deliberately short. For the full architecture, see [STRUCTURE.md](STRUCTURE.md);
+for every option, [OPTIONS.md](OPTIONS.md).
+
+---
+
+## 1. The 60-second mental model
+
+Nomarchy is a NixOS flake. Three layers, top to bottom:
+
+```
+core/      foundation     → the OS + base user env that must always exist
+features/  the desktop    → apps, Hyprland/waybar, user scripts (opt-in modules)
+themes/    the look       → palettes (data) + engine (logic) + templates (.tpl)
+```
+
+Everything else is plumbing: `lib/` (shared Nix helpers), `installer/` + `hosts/`
+(how it gets onto a disk), `bin/` (repo tooling, **not** shipped to users),
+`docs/`.
+
+The flake wires it up as two NixOS/HM modules:
+- `nixosModules.system` ← `core/system/` (the OS)
+- `nixosModules.home`   ← `features/` (which itself imports `core/home/` + the theme engine)
+
+### The two things that confuse everyone
+
+There are **two** places that look like "app config," and they are *different
+concepts*:
+
+| Path | What it is |
+|------|-----------|
+| `features/apps/<app>/` | The **module** for an app — turns it on, sets its config. This is *code*. |
+| `core/home/config/nomarchy/default/<app>/` | A **payload** of files copied verbatim to `~/.config/nomarchy/default/<app>/` at rebuild. This is *data* that scripts + the theme engine read at runtime. |
+
+So when you saw `alacritty` in both trees: `features/apps/alacritty/` is the app
+module; `core/home/config/nomarchy/default/alacritty/screensaver.toml` is just a
+screensaver file that happens to be named after alacritty. Not a duplicate.
+
+**Rule of thumb:** changing how an app *behaves* → `features/apps/`. Changing a
+file that lands in the user's home and gets read at runtime → `core/home/config/`.
+
+---
+
+## 2. "I want to change X" → go here
+
+| I want to… | Go to |
+|------------|-------|
+| Tweak an app's settings (kitty, btop, tmux…) | `features/apps/<app>/default.nix` (+ its `config/`) |
+| Change Hyprland behaviour / keybinds | `features/desktop/hyprland/` and `core/home/config/nomarchy/default/hypr/` |
+| Change the status bar | `features/desktop/waybar/` |
+| Add/remove a theme | `themes/palettes/<name>/` |
+| Change how theming is applied | `themes/engine/loader.nix` |
+| Add a **user** command (`nomarchy-foo`) | `features/scripts/utils/` |
+| Add a **system/root** command | `core/system/scripts/` |
+| Add a NixOS option (`nomarchy.system.*`) | `core/system/options.nix` |
+| Add a HM option (`nomarchy.*`) | `core/home/options.nix` |
+| Change what the installer writes | `installer/install.sh` |
+
+When in doubt, grep for an existing example of the thing you're changing and copy
+its shape — the repo is very consistent *within* each of these buckets.
+
+---
+
+## 3. The build/test loop
+
+You almost never need a full install to test a change. From the repo root:
+
+```bash
+# Evaluate + build the whole system WITHOUT activating it (safe, no sudo):
+nixos-rebuild build --flake .#default --impure
+# → prints "Done. The new configuration is /nix/store/…" if it builds.
+# (drops a ./result symlink you can delete)
+```
+
+On a real install, the user-facing commands are:
+
+```bash
+sys-update    # sudo nixos-rebuild switch --flake .#default --impure   (system)
+env-update    # home-manager switch --flake .#default --impure         (user env)
+```
+
+`bin/utils/` holds repo tooling that regenerates the auto-docs
+(`SCRIPTS.md`, `KEYBINDINGS.md`). A pre-commit hook runs them; you rarely call
+them by hand.
+
+---
+
+## 4. Where scripts live (the one rule)
+
+There are **four** script homes, by **execution context**, not by topic:
+
+| Dir | Context | Example |
+|-----|---------|---------|
+| `bin/utils/` | Repo tooling, never shipped | `nomarchy-docs-scripts` |
+| `core/system/scripts/` | System / root / hardware | `nomarchy-setup-dns`, `nomarchy-toggle-hybrid-gpu` |
+| `features/scripts/utils/` | User / desktop | `nomarchy-menu`, `nomarchy-launch-walker` |
+| `themes/engine/scripts/` | Theme engine | **`nomarchy-theme-set`**, `nomarchy-theme-bg-set`, `nomarchy-theme-next` |
+
+> **Heads-up:** the `nomarchy-theme-*` family lives in `themes/engine/scripts/`, **not**
+> `features/scripts/utils/`. All four dirs are built onto the user's `$PATH`, so at
+> runtime `nomarchy-theme-set "Tokyo Night"` just works regardless of which dir it's in —
+> the split only matters when you're hunting for the *source*. Find any script's source
+> fast with `grep -rl nomarchy-theme-set .` rather than guessing the directory.
+
+New script? Ask: *does it need root or system packages?* → `core/system/scripts/`.
+*Is it user-facing desktop glue?* → `features/scripts/utils/`. *Only useful inside
+this repo?* → `bin/utils/`. Scripts are found by name on `$PATH`, so moving one
+between the first two means changing the Nix derivation it's built into, not the
+call sites.
+
+---
+
+## 5. How theming works (the short version)
+
+1. The active theme name lives in **state**: `~/.config/nomarchy/state.json`
+   (runtime) → mirrored into `/etc/nixos/nomarchy-state.nix` for reproducibility.
+2. `themes/engine/loader.nix` reads that name and deploys the matching themed
+   files (btop theme, kitty colors, waybar css…) into `~/.config/`.
+3. `themes/templates/*.tpl` are filled with the palette's colors to produce
+   dynamic configs.
+4. Switching a theme runs scripts that rewrite those files and then *reload* the
+   affected apps (this is what the `nomarchy-restart-*` family is for — each app
+   reloads differently: SIGUSR2, a full restart, etc.).
+
+---
+
+## 6. Walker + elephant (so you can decide on the menus later)
+
+This is the bit you wanted to understand before changing anything. There are
+**two separate programs**:
+
+- **Walker** — the *front-end*. A Rust/GTK4 window that shows a list and a
+  search box. It's what you see. Started as a user service
+  (`programs.walker`, `runAsService = true`).
+- **elephant** — the *back-end*. A Go daemon that actually produces the data
+  (apps, calculator, clipboard, emoji, and **custom menus**). Walker talks to it
+  over a Unix socket. Config lives in `features/apps/elephant/config/`, deployed
+  to `~/.config/elephant/`.
+
+Think: **Walker draws, elephant supplies.**
+
+### How a menu reaches the screen
+
+There are two completely different paths, and only one of them touches Lua:
+
+**Path A — `--dmenu` (no elephant data providers, no Lua).**
+Used by `nomarchy-menu`, `nomarchy-font`, the keybindings viewer, etc.
+You pipe plain text lines into `walker --dmenu`; Walker shows them and prints the
+chosen line back. **Text only** — Walker's dmenu mode literally cannot show icons
+or an image preview pane (verified in its source: each line becomes `item.text`
+and the preview box is hidden). This is the simple, dependency-free path.
+
+```
+echo -e "Option A\nOption B" | walker --dmenu -p "Pick…"
+```
+
+**Path B — elephant custom menu providers (`-m menus:<name>`).**
+Used by the theme picker and wallpaper picker. Here elephant loads a *menu
+provider* from `~/.config/elephant/menus/`. A menu provider can be:
+- a **TOML** file with a *static* list of entries — each entry can have an
+  `icon`, a `preview`/`preview_type`, and `actions`; or
+- a **Lua** file (`run = "lua:…"`) whose `GetEntries()` returns a *dynamic*
+  list built at runtime.
+
+The theme/wallpaper menus need a *variable* list (one entry per theme/wallpaper,
+discovered on disk) **and** an image preview. In elephant, the only built-in way
+to generate a variable-length list is Lua's `GetEntries()`. That's the entire
+reason `nomarchy_themes.lua` and `nomarchy_background_selector.lua` exist — and
+they're the *only* Lua in the whole repo.
+
+### The decision space (for later)
+
+If you want to drop Lua but keep Walker, the trade is purely about previews:
+
+- **Keep previews** → replace the two `.lua` files with a small **bash generator**
+  that writes *static* elephant TOML menus (one `[[entries]]` per theme/wallpaper,
+  each with `preview = "…/preview.png"`), regenerated at rebuild + on theme
+  switch. No Lua, keeps the preview pane, adds one generator script.
+- **Drop previews** → route the theme/wallpaper pickers through `walker --dmenu`
+  like the other menus. Deletes both `.lua` files, the elephant menu config for
+  them, and the `pkgs.lua` dependency. Simplest possible; theme/wallpaper become
+  plain text lists.
+
+Nothing here is decided yet — this section is just the map.
+
+### Key files for the menu system
+
+| File | Role |
+|------|------|
+| `features/scripts/utils/nomarchy-launch-walker` | Wrapper: starts elephant + walker services, routes `--dmenu` vs provider calls |
+| `features/scripts/utils/nomarchy-menu` | The big interactive menu (all Path A / dmenu) |
+| `features/apps/walker.nix` | Walker module + config (prefixes, providers, theme) |
+| `features/apps/elephant/config/` | elephant providers (calc, symbols, **menus/**) |
+| `features/apps/elephant/config/menus/*.lua` | The two dynamic preview menus (the only Lua) |
+
+---
+
+## 7. Gotchas worth knowing
+
+- **`--impure` is required** on rebuilds — the config reads runtime state
+  (`state.json`) outside the flake.
+- **`docs/SCRIPTS.md` and `docs/KEYBINDINGS.md` are auto-generated.** Don't edit by
+  hand; the pre-commit hook (and CI) regenerate and verify them.
+- **The deep `core/home/config/nomarchy/default/…` tree is a payload**, deployed
+  wholesale to `~/.config/nomarchy/default/`. Moving files out of it will break the
+  scripts/loader that read those exact runtime paths.
+- **Two parallel module systems**: `core/system` = NixOS (root), `features` +
+  `core/home` = Home Manager (user). A setting only works if it's in the right one.

docs/creating-themes.md

@@ -175,17 +175,26 @@ decoration {
 
 ## Step 6: Template Variables
 
-Nomarchy has a template system that generates app configs from your `colors.toml`. Templates in `themes/templates/*.tpl` use placeholder syntax:
+Nomarchy has a small template system that generates per-palette files from your `colors.toml` at `nomarchy-theme-set` time. Templates in `themes/templates/*.tpl` use placeholder syntax:
 
-| Syntax              | Example Value | Description                    |
-|---------------------|---------------|--------------------------------|
-| `{{ background }}`  | `#2d353b`     | Color value as-is (with `#`)   |
-| `{{ background_strip }}` | `2d353b` | Color value without `#`        |
-| `{{ background_rgb }}` | `45,53,59`  | Color as decimal RGB           |
+| Syntax                  | Example Value | Description                  |
+|-------------------------|---------------|------------------------------|
+| `{{ background }}`      | `#2d353b`     | Color value as-is (with `#`) |
+| `{{ background_strip }}`| `2d353b`      | Color value without `#`      |
+| `{{ background_rgb }}`  | `45,53,59`    | Color as decimal RGB         |
 
-Every key from `colors.toml` is available as a template variable. Templates are processed automatically by `nomarchy-theme-set-templates` when switching themes.
+Every key from `colors.toml` is available as a template variable. The script (`nomarchy-theme-set-templates`) processes each template into `~/.config/nomarchy/current/theme/<name>` only when no file is already there — so it acts as a fallback for palettes that don't ship the file themselves.
 
-To add custom templates, place `.tpl` files in `~/.config/nomarchy/themed/`. User templates take priority over built-in ones.
+Two built-in templates ship:
+
+| Template            | Output                                         | Consumed by                                                                 |
+|---------------------|------------------------------------------------|-----------------------------------------------------------------------------|
+| `obsidian.css.tpl`  | `~/.config/nomarchy/current/theme/obsidian.css` | `nomarchy-theme-set-obsidian` copies it into every Obsidian vault           |
+| `keyboard.rgb.tpl`  | `~/.config/nomarchy/current/theme/keyboard.rgb` | `nomarchy-theme-set-keyboard-asus-rog` calls `asusctl aura effect static`   |
+
+Everything else that used to ship a template (`alacritty.toml.tpl`, `btop.theme.tpl`, `chromium.theme.tpl`, `ghostty.conf.tpl`, `hyprland.conf.tpl`, `hyprlock.conf.tpl`, `kitty.conf.tpl`, `swayosd.css.tpl`, `hyprland-preview-share-picker.css.tpl`) has been removed: those apps are themed via Stylix, declarative Home-Manager options, or per-palette Nix generators in `themes/engine/files.nix` — the template path was always shadowed by an earlier write.
+
+To add a custom template, drop a `.tpl` file in `~/.config/nomarchy/themes/templates/`. User templates take priority over built-in ones.
 
 ## Step 7: Preview Image (Optional)
 

features/apps/alacritty/default.nix

@@ -1,25 +1,27 @@
 { config, pkgs, lib, ... }:
 
 {
-  programs.alacritty = {
-    enable = lib.mkDefault true;
-    settings = lib.mkDefault {
-      env = {
-        TERM = "xterm-256color";
-      };
-      terminal = {
-        osc52 = "CopyPaste";
-      };
-      window = {
-        padding = { x = 14; y = 14; };
-        decorations = "None";
-      };
-      keyboard = {
-        bindings = [
-          { key = "Insert"; mods = "Shift"; action = "Paste"; }
-          { key = "Insert"; mods = "Control"; action = "Copy"; }
-          { key = "Return"; mods = "Shift"; chars = "\\u001B\\r"; }
-        ];
+  config = lib.mkIf config.nomarchy.apps.alacritty.enable {
+    programs.alacritty = {
+      enable = lib.mkDefault true;
+      settings = lib.mkDefault {
+        env = {
+          TERM = "xterm-256color";
+        };
+        terminal = {
+          osc52 = "CopyPaste";
+        };
+        window = {
+          padding = { x = 14; y = 14; };
+          decorations = "None";
+        };
+        keyboard = {
+          bindings = [
+            { key = "Insert"; mods = "Shift"; action = "Paste"; }
+            { key = "Insert"; mods = "Control"; action = "Copy"; }
+            { key = "Return"; mods = "Shift"; chars = "\\u001B\\r"; }
+          ];
+        };
       };
     };
   };

features/apps/btop/config/btop.conf

@@ -2,7 +2,7 @@
 
 #* Name of a btop++/bpytop/bashtop formatted ".theme" file, "Default" and "TTY" for builtin themes.
 #* Themes should be placed in "../share/btop/themes" relative to binary or "$HOME/.config/btop/themes"
-color_theme = "current"
+color_theme = "nomarchy"
 
 #* If the theme set background should be shown, set to False if you want terminal background transparency.
 theme_background = True

features/apps/btop/default.nix

@@ -1,5 +1,8 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."btop/btop.conf".source = ./config/btop.conf;
+  config = lib.mkIf config.nomarchy.apps.btop.enable {
+    programs.btop.enable = lib.mkDefault true;
+    xdg.configFile."btop/btop.conf".source = ./config/btop.conf;
+  };
 }

features/apps/chromium/config/Default/Preferences

@@ -1,15 +0,0 @@
-{
-  "extensions": {
-    "theme": {
-      "id": "",
-      "use_system": false,
-      "use_custom": false
-    }
-  },
-  "browser": {
-    "theme": {
-      "color_scheme": 2,
-      "user_color": 2
-    }
-  }
-}

features/apps/chromium/default.nix

@@ -1,8 +0,0 @@
-{ config, pkgs, lib, ... }:
-
-{
-  xdg.configFile."chromium/Default" = {
-    source = ./config/Default;
-    recursive = true;
-  };
-}

features/apps/elephant/config/menus/nomarchy_background_selector.lua

@@ -46,7 +46,9 @@ function GetEntries()
 
   for _, wallpaper_dir in ipairs(dirs) do
     local handle = io.popen(
-      "find " .. ShellEscape(wallpaper_dir)
+      -- -L so -type f follows the home-manager symlinks the backgrounds are
+      -- deployed as (the nomarchy_themes.lua provider does the same).
+      "find -L " .. ShellEscape(wallpaper_dir)
         .. " -maxdepth 1 -type f \\( -name '*.jpg' -o -name '*.jpeg' -o -name '*.png' -o -name '*.gif' -o -name '*.bmp' -o -name '*.webp' \\) 2>/dev/null | sort"
     )
     if handle then

features/apps/elephant/default.nix

@@ -1,8 +1,10 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."elephant" = {
-    source = ./config;
-    recursive = true;
+  config = lib.mkIf config.nomarchy.apps.elephant.enable {
+    xdg.configFile."elephant" = {
+      source = ./config;
+      recursive = true;
+    };
   };
 }

features/apps/ghostty/default.nix

@@ -1,5 +1,7 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."ghostty/config".source = ./config/config;
+  config = lib.mkIf config.nomarchy.apps.ghostty.enable {
+    xdg.configFile."ghostty/config".source = ./config/config;
+  };
 }

features/apps/kitty/default.nix

@@ -1,5 +1,8 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."kitty/kitty.conf".source = ./config/kitty.conf;
+  config = lib.mkIf config.nomarchy.apps.kitty.enable {
+    programs.kitty.enable = lib.mkDefault true;
+    xdg.configFile."kitty/kitty.conf".source = ./config/kitty.conf;
+  };
 }

features/apps/lazygit/default.nix

@@ -1,5 +1,8 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."lazygit/config.yml".source = ./config/config.yml;
+  config = lib.mkIf config.nomarchy.apps.lazygit.enable {
+    home.packages = [ pkgs.lazygit ];
+    xdg.configFile."lazygit/config.yml".source = ./config/config.yml;
+  };
 }

features/apps/swayosd.nix

@@ -1,41 +1,43 @@
 { config, pkgs, lib, ... }:
 
 {
-  services.swayosd = {
-    enable = lib.mkDefault true;
-    stylePath = lib.mkDefault "${config.home.homeDirectory}/.config/swayosd/style.css";
+  config = lib.mkIf config.nomarchy.apps.swayosd.enable {
+    services.swayosd = {
+      enable = lib.mkDefault true;
+      stylePath = lib.mkDefault "${config.home.homeDirectory}/.config/swayosd/style.css";
+    };
+
+    xdg.configFile."swayosd/style.css".text = lib.mkDefault ''
+      @define-color background-color #${config.colorScheme.palette.base00};
+      @define-color border-color #${config.colorScheme.palette.base0E};
+      @define-color label #${config.colorScheme.palette.base05};
+      @define-color image #${config.colorScheme.palette.base05};
+      @define-color progress #${config.colorScheme.palette.base0B};
+
+      window {
+        border-radius: 0;
+        opacity: 0.97;
+        border: 2px solid @border-color;
+        background-color: @background-color;
+      }
+
+      label {
+        font-family: '${config.nomarchy.fonts.monospace}';
+        font-size: 11pt;
+        color: @label;
+      }
+
+      image {
+        color: @image;
+      }
+
+      progressbar {
+        border-radius: 0;
+      }
+
+      progress {
+        background-color: @progress;
+      }
+    '';
   };
-
-  xdg.configFile."swayosd/style.css".text = lib.mkDefault ''
-    @define-color background-color #${config.colorScheme.palette.base00};
-    @define-color border-color #${config.colorScheme.palette.base0E};
-    @define-color label #${config.colorScheme.palette.base05};
-    @define-color image #${config.colorScheme.palette.base05};
-    @define-color progress #${config.colorScheme.palette.base0B};
-
-    window {
-      border-radius: 0;
-      opacity: 0.97;
-      border: 2px solid @border-color;
-      background-color: @background-color;
-    }
-
-    label {
-      font-family: '${config.nomarchy.fonts.monospace}';
-      font-size: 11pt;
-      color: @label;
-    }
-
-    image {
-      color: @image;
-    }
-
-    progressbar {
-      border-radius: 0;
-    }
-
-    progress {
-      background-color: @progress;
-    }
-  '';
 }

features/apps/tmux/default.nix

@@ -1,5 +1,8 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."tmux/tmux.conf".source = ./config/tmux.conf;
+  config = lib.mkIf config.nomarchy.apps.tmux.enable {
+    programs.tmux.enable = lib.mkDefault true;
+    xdg.configFile."tmux/tmux.conf".source = ./config/tmux.conf;
+  };
 }

features/apps/vscode.nix

@@ -7,7 +7,78 @@ let
   else
     { name = "Default Dark Modern"; };
 
-  # Development extensions that match the system theme
+  # Theme extensions matching palette vscode.json `extension` fields.
+  # Always installed because workbench.colorTheme is set unconditionally
+  # from the active palette — without the matching extension VSCode
+  # silently falls back to its default theme.
+  #
+  # The list is split because nixpkgs doesn't package every theme our
+  # palettes use. Six are in pkgs.vscode-extensions; the rest are pulled
+  # from the VSCode marketplace via extensionFromVscodeMarketplace with
+  # publisher / name / version / sha256 pinned. To refresh a version,
+  # bump the `version` and `nix-prefetch-url` the new .vsix:
+  #
+  #   URL='https://${publisher}.gallery.vsassets.io/_apis/public/gallery/publisher/${publisher}/extension/${name}/${version}/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage'
+  #   nix store prefetch-file --hash-type sha256 "$URL"
+  #
+  # Three palette extensions remain unfixed because the corresponding
+  # marketplace entries don't exist — Bjarne.ethereal-nomarchy,
+  # Bjarne.hackerman-nomarchy, Bjarne.vantablack-nomarchy. The matching
+  # palettes (ethereal, hackerman, vantablack) still fall back to
+  # VSCode's default theme; see the ROADMAP Later row for next steps.
+
+  marketplaceExtensions = with pkgs.vscode-utils; [
+    (extensionFromVscodeMarketplace {           # everforest, summer-day, summer-night
+      publisher = "sainnhe"; name = "everforest"; version = "0.3.0";
+      sha256 = "sha256-nZirzVvM160ZTpBLTimL2X35sIGy5j2LQOok7a2Yc7U=";
+    })
+    (extensionFromVscodeMarketplace {           # flexoki-light
+      publisher = "shadesOfBuntu"; name = "flexoki-light"; version = "1.0.0";
+      sha256 = "sha256-//y9uvIUGGDEhd8inDHvNy2e1IKNx6hSfO9sxNOTcUE=";
+    })
+    (extensionFromVscodeMarketplace {           # kanagawa
+      publisher = "qufiwefefwoyn"; name = "kanagawa"; version = "1.5.1";
+      sha256 = "sha256-AGGioXcK/fjPaFaWk2jqLxovUNR59gwpotcSpGNbj1c=";
+    })
+    (extensionFromVscodeMarketplace {           # lumon
+      publisher = "oldjobobo"; name = "lumon-theme"; version = "0.0.7";
+      sha256 = "sha256-YlO1r1JjaumiicvMk5fBr+PZCYFaII03PaLiyqE35Go=";
+    })
+    (extensionFromVscodeMarketplace {           # matte-black
+      publisher = "TahaYVR"; name = "matteblack"; version = "1.0.3";
+      sha256 = "sha256-wn/llGidzyPd91XT3xVqAvaU4NcTTggTSz8WmUcV8HM=";
+    })
+    (extensionFromVscodeMarketplace {           # miasma
+      publisher = "oldjobobo"; name = "miasma-theme"; version = "0.1.1";
+      sha256 = "sha256-STFTGFhQqxocr+YNFQp36IQWJRKTDBgBg4MOCOq1IPQ=";
+    })
+    (extensionFromVscodeMarketplace {           # osaka-jade
+      publisher = "jovejonovski"; name = "ocean-green"; version = "1.1.2";
+      sha256 = "sha256-sUNjnzqXya23Uieg8RLcEfnxiX0ImZ6CIjFtSJ66vM4=";
+    })
+    (extensionFromVscodeMarketplace {           # retro-82
+      publisher = "oldjobobo"; name = "retro-82-theme"; version = "0.1.4";
+      sha256 = "sha256-GqFeFFG5scO7CEXlKjj6uoilCoUfpRaQa5jBSnNJyJA=";
+    })
+    (extensionFromVscodeMarketplace {           # ristretto
+      publisher = "monokai"; name = "theme-monokai-pro-vscode"; version = "2.0.13";
+      sha256 = "sha256-5bKwVzDfZoSipR04tPDx9jbKhYsSsa3z6Ei9E2jhudo=";
+    })
+    (extensionFromVscodeMarketplace {           # white
+      publisher = "Bjarne"; name = "white-theme"; version = "0.0.1";
+      sha256 = "sha256-3ZyWNVlQO3Tof49FFF3OImuo7hgtJXLNuwQ+iHjzzGk=";
+    })
+  ];
+
+  themeExtensions = (with pkgs.vscode-extensions; [
+    catppuccin.catppuccin-vsc                  # catppuccin, catppuccin-latte
+    enkia.tokyo-night                          # tokyo-night
+    arcticicestudio.nord-visual-studio-code    # nord
+    mvllow.rose-pine                           # rose-pine
+    jdinhlife.gruvbox                          # gruvbox
+  ]) ++ marketplaceExtensions;
+
+  # Development extensions — opt-in via nomarchy.vscode.devExtensions.
   devExtensions = with pkgs.vscode-extensions; [
     # Language support
     ms-python.python
@@ -22,36 +93,26 @@ let
     esbenp.prettier-vscode
     dbaeumer.vscode-eslint
     bradlc.vscode-tailwindcss
-
-    # Theme extensions (provide color themes matching nomarchy palettes)
-    catppuccin.catppuccin-vsc
-    enkia.tokyo-night
-    arcticicestudio.nord-visual-studio-code
-    sainnhe.everforest
-    mvllow.rose-pine
   ];
 in
 {
-  options.nomarchy.vscode = {
-    devExtensions = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      description = "Whether to install development extensions for VSCode.";
-    };
-  };
-
-  config = {
+  config = lib.mkIf config.nomarchy.apps.vscode.enable {
     programs.vscode = {
       enable = lib.mkDefault true;
       package = lib.mkDefault pkgs.vscode;
-      profiles.default.userSettings = lib.mkDefault {
-        "update.mode" = "none";
-        "workbench.colorTheme" = themeConfig.name;
-        "window.titleBarStyle" = "custom";
-        "editor.fontFamily" = "'${config.nomarchy.fonts.monospace}', 'Droid Sans Mono', monospace";
-        "terminal.integrated.fontFamily" = config.nomarchy.fonts.monospace;
+      profiles.default = {
+        userSettings = lib.mkDefault {
+          "update.mode" = "none";
+          "workbench.colorTheme" = themeConfig.name;
+          "window.titleBarStyle" = "custom";
+          "editor.fontFamily" = "'${config.nomarchy.fonts.monospace}', 'Droid Sans Mono', monospace";
+          "terminal.integrated.fontFamily" = config.nomarchy.fonts.monospace;
+        };
+        extensions = lib.mkDefault (
+          themeExtensions
+          ++ lib.optionals config.nomarchy.apps.vscode.devExtensions devExtensions
+        );
       };
-      extensions = lib.mkIf config.nomarchy.vscode.devExtensions (lib.mkDefault devExtensions);
     };
   };
 }

features/apps/walker.nix

@@ -1,49 +1,51 @@
 { config, pkgs, lib, ... }:
 
 {
-  home.packages = [ pkgs.lua ];
+  config = lib.mkIf config.nomarchy.apps.walker.enable {
+    home.packages = [ pkgs.lua ];
 
-  programs.walker = {
-    enable = lib.mkDefault true;
-    runAsService = lib.mkDefault true;
-    config = lib.mkDefault {
-      theme = "nomarchy";
-      ui = {
-        anchors = {
-          top = true;
+    programs.walker = {
+      enable = lib.mkDefault true;
+      runAsService = lib.mkDefault true;
+      config = lib.mkDefault {
+        theme = "nomarchy";
+        ui = {
+          anchors = {
+            top = true;
+          };
+        };
+        selection_wrap = true;
+        hide_action_hints = true;
+        placeholders = {
+          "default" = { input = " Search..."; list = "No Results"; };
+        };
+        keybinds = {
+          quick_activate = [];
+        };
+        columns = {
+          symbols = 1;
+        };
+        providers = {
+          max_results = 256;
+          default = [
+            "desktopapplications"
+            "websearch"
+          ];
+          prefixes = [
+            { prefix = "/"; provider = "providerlist"; }
+            { prefix = "."; provider = "files"; }
+            { prefix = ":"; provider = "symbols"; }
+            { prefix = "="; provider = "calc"; }
+            { prefix = "@"; provider = "websearch"; }
+            { prefix = "$"; provider = "clipboard"; }
+          ];
         };
       };
-      selection_wrap = true;
-      hide_action_hints = true;
-      placeholders = {
-        "default" = { input = " Search..."; list = "No Results"; };
+      themes."nomarchy" = lib.mkDefault {
+        style = ''
+          @import "${config.home.homeDirectory}/.config/nomarchy/current/theme/apps/walker/style.css";
+        '';
       };
-      keybinds = {
-        quick_activate = [];
-      };
-      columns = {
-        symbols = 1;
-      };
-      providers = {
-        max_results = 256;
-        default = [
-          "desktopapplications"
-          "websearch"
-        ];
-        prefixes = [
-          { prefix = "/"; provider = "providerlist"; }
-          { prefix = "."; provider = "files"; }
-          { prefix = ":"; provider = "symbols"; }
-          { prefix = "="; provider = "calc"; }
-          { prefix = "@"; provider = "websearch"; }
-          { prefix = "$"; provider = "clipboard"; }
-        ];
-      };
-    };
-    themes."nomarchy" = lib.mkDefault {
-      style = ''
-        @import "${config.home.homeDirectory}/.config/nomarchy/current/theme/apps/walker/style.css";
-      '';
     };
   };
 }

features/default.nix

@@ -15,7 +15,6 @@ in
     ../themes/engine/stylix.nix
     ./apps/alacritty/default.nix
     ./apps/btop/default.nix
-    ./apps/chromium/default.nix
     ./apps/elephant/default.nix
     ./apps/ghostty/default.nix
     ./apps/kitty/default.nix
@@ -39,15 +38,12 @@ in
   # Enable neovim program module (required for stylix integration)
   programs.neovim.enable = lib.mkDefault true;
 
-  home.packages = lib.mkDefault (with pkgs; [
-    # Core applications
-    firefox
-    xfce.thunar
-
-    # Media
-    imv              # Image viewer
-    mpv              # Video player
-
+  # NOT mkDefault: home.packages is a list that MERGES across modules. At
+  # mkDefault priority this whole curated list is dropped the moment any
+  # other module sets home.packages at normal priority (features/scripts,
+  # the installer's profile packages), silently removing firefox, mako,
+  # hyprlock, mpv, etc. — which broke notifications and the lock screen.
+  home.packages = (with pkgs; [
     # Hyprland ecosystem
     swww             # Wallpaper daemon
     mako             # Notification daemon
@@ -70,7 +66,8 @@ in
     gum              # TUI components for scripts
     xdg-terminal-exec
     swaybg
-    rofi-wayland
+    rofi   # rofi-wayland was merged into rofi upstream
+    calcurse         # TUI calendar
 
     # Theming — cursor package stays here; icon theme packages are pulled in
     # dynamically by themes/engine/stylix.nix via nomarchyLib.iconThemePackage
@@ -78,3 +75,4 @@ in
     bibata-cursors
   ]);
 }
+

features/desktop/hyprland-preview-share-picker/config/config.yaml

@@ -1,71 +0,0 @@
-# paths to stylesheets on the filesystem which should be applied to the application
-#
-# relative paths are resolved relative to the location of the config file
-stylesheets: ["../nomarchy/current/theme/hyprland-preview-share-picker.css"]
-# default page selected when the picker is opened
-default_page: outputs
-
-window:
-  # height of the application window
-  height: 500
-  # width of the application window
-  width: 1000
-
-image:
-  # size to which the images should be internally resized to reduce the memory footprint
-  resize_size: 500
-  # target size of the longer side of the image widget
-  widget_size: 150
-
-classes:
-  # css classname of the window
-  window: window
-  # css classname of the card containing an image and a label
-  image_card: card
-  # css classname of the card containing an image and a label when the image is still being loaded
-  image_card_loading: card-loading
-  # css classname of the image inside the card
-  image: image
-  # css classname of the label inside the card
-  image_label: image-label
-  # css classname of the notebook containing all pages
-  notebook: notebook
-  # css classname of a label of the notebook
-  tab_label: tab-label
-  # css classname of a notebook page (e.g. windows container)
-  notebook_page: page
-  # css classname of the region selection button
-  region_button: region-button
-  # css classname of the button containing the session restore checkbox and label
-  restore_button: restore-button
-
-windows:
-  # minimum amount of image cards per row on the windows page
-  min_per_row: 3
-  # maximum amount of image cards per row on the windows page
-  max_per_row: 999
-  # number of clicks needed to select a window
-  clicks: 1
-  # spacing in pixels between the window cards
-  spacing: 12
-
-outputs:
-  # number of clicks needed to select an output
-  clicks: 1
-  # spacing in pixels between the outputs in the layout
-  # note: the spacing is applied from both sides (the gap is `spacing * 2`)
-  spacing: 6
-  # show the label with the output name
-  show_label: false
-  # size the output cards respectively to their scaling
-  respect_output_scaling: true
-
-region:
-  # command to run for region selection
-  # the output needs to be in the <output>@<x>,<y>,<w>,<h> (e.g. DP-3@2789,436,756,576) format
-  command: slurp -f '%o@%x,%y,%w,%h'
-
-# hide the token restore checkbox and use the default value instead
-hide_token_restore: true
-# enable debug logs by default
-debug: false

features/desktop/hyprland/config/autostart.conf

@@ -1,2 +0,0 @@
-# Extra autostart processes
-# exec-once = uwsm-app -- my-service

features/desktop/hyprland/config/hyprlock.conf

@@ -1,43 +0,0 @@
-source = ~/.config/nomarchy/current/theme/hyprlock.conf
-
-general {
-    ignore_empty_input = true
-}
-
-background {
-    monitor =
-    color = $color
-    path = ~/.config/nomarchy/current/background
-    blur_passes = 3
-}
-
-animations {
-    enabled = false
-}
-
-input-field {
-    monitor =
-    size = 650, 100
-    position = 0, 0
-    halign = center
-    valign = center
-
-    inner_color = $inner_color
-    outer_color = $outer_color
-    outline_thickness = 4
-
-    font_family = JetBrainsMono Nerd Font
-    font_color = $font_color
-
-    placeholder_text = Enter Password
-    check_color = $check_color
-    fail_text = <i>$FAIL ($ATTEMPTS)</i>
-
-    rounding = 0
-    shadow_passes = 0
-    fade_on_empty = false
-}
-
-auth {
-    fingerprint:enabled = false
-}

features/desktop/hyprland/config/hyprsunset.conf

@@ -1,14 +0,0 @@
-# Makes hyprsunset do nothing to the screen by default
-# Without this, the default applies some tint to the monitor
-profile {
-    time = 07:00
-    identity = true
-}
-
-# To enable auto switch to nightlight, set in your .config/hypr/autostart:
-# exec-once = uwsm app -- hyprsunset
-# and use the following:
-# profile {
-#     time = 20:00
-#     temperature = 4000
-# }

features/desktop/hyprland/config/looknfeel.conf

@@ -1,34 +0,0 @@
-# Change the default Nomarchy look'n'feel
-
-# https://wiki.hyprland.org/Configuring/Variables/#general
-general {
-    # No gaps between windows or borders
-    # gaps_in = 0
-    # gaps_out = 0
-    # border_size = 0
-
-    # Change to niri-like side-scrolling layout
-    # layout = scrolling
-}
-
-# https://wiki.hyprland.org/Configuring/Variables/#decoration
-decoration {
-    # Use round window corners
-    # rounding = 8
-
-    # Dim unfocused windows (0.0 = no dim, 1.0 = fully dimmed)
-    # dim_inactive = true
-    # dim_strength = 0.15
-}
-
-# https://wiki.hyprland.org/Configuring/Variables/#animations
-animations {
-    # Disable all animations
-    # enabled = no
-}
-
-# https://wiki.hypr.land/Configuring/Variables/#layout
-layout {
-    # Avoid overly wide single-window layouts on wide screens
-    # single_window_aspect_ratio = 1 1
-}

features/desktop/hyprland/config/monitors.conf

@@ -1,23 +0,0 @@
-# See https://wiki.hyprland.org/Configuring/Monitors/
-# List current monitors and resolutions possible: hyprctl monitors
-# Format: monitor = [port], resolution, position, scale
-
-# Optimized for retina-class 2x displays, like 13" 2.8K, 27" 5K, 32" 6K.
-#env = GDK_SCALE,2
-#monitor=,preferred,auto,auto
-
-# Good compromise for 27" or 32" 4K monitors (but fractional!)
-# env = GDK_SCALE,1.75
-# monitor=,preferred,auto,1.6
-
-# Straight 1x setup for low-resolution displays like 1080p or 1440p
-# Or for ultrawide monitors like 34" 3440x1440 or 49" 5120x1440
- env = GDK_SCALE,1
- monitor=,highres,auto,1
-
-# Portrait/rotated secondary monitor (transform: 1 = 90°, 3 = 270°)
-# monitor = DP-2, preferred, auto, 1, transform, 1
-
-# Example for Framework 13 w/ 6K XDR Apple display
-# monitor = DP-5, 6016x3384@60, auto, 2
-# monitor = eDP-1, 2880x1920@120, auto, 2

features/desktop/hyprland/config/xdph.conf

@@ -1,4 +0,0 @@
-screencopy {
-    allow_token_by_default = true
-    custom_picker_binary = hyprland-preview-share-picker
-}

features/desktop/hyprland/default.nix

@@ -48,13 +48,18 @@ in
     '';
   };
 
-  # Deploy Hyprland configuration files
+  # Deploy Hyprland configuration files. Only the files that nomarchy.conf
+  # actually sources are deployed here — looknfeel.conf and autostart.conf
+  # live under ~/.config/nomarchy/default/hypr/ and are deployed by the
+  # core/home bulk-nomarchy dir, so duplicating them here was dead surface.
   xdg.configFile."hypr/nomarchy.conf".source = ./config/nomarchy.conf;
-  xdg.configFile."hypr/monitors.conf".source = lib.mkDefault ./config/monitors.conf;
+  xdg.configFile."hypr/monitors.conf".text = lib.mkDefault ''
+    # Auto-generated by Nomarchy features/desktop/hyprland/default.nix
+    # monitor = [port], resolution, position, scale
+    monitor = , highres, auto, ${config.nomarchy.hyprland.scale}
+  '';
   xdg.configFile."hypr/input.conf".source = lib.mkDefault ./config/input.conf;
   xdg.configFile."hypr/bindings.conf".source = lib.mkDefault ./config/bindings.conf;
-  xdg.configFile."hypr/looknfeel.conf".source = lib.mkDefault ./config/looknfeel.conf;
-  xdg.configFile."hypr/autostart.conf".source = lib.mkDefault ./config/autostart.conf;
 
   # Run swaybg as a proper systemd user service rather than a Hyprland exec-once.
   # exec-once fails silently (black screen with no visible error) when timing

features/desktop/nightlight.nix

@@ -1,11 +1,21 @@
 { config, lib, ... }:
 
-let
-  temp = toString (if config.nomarchy.toggles.nightlight then config.nomarchy.nightlightTemperature else 6500);
-in
+# hyprsunset (the blue-light filter) is gated on `nomarchy.toggles.nightlight`
+# so a disabled toggle means no process runs — symmetric with how
+# `services.hypridle.enable` is wired off `toggles.idle`. The temperature
+# comes from `nomarchy.nightlightTemperature`, evaluated at Nix-eval time
+# and baked into `extraArgs`. The toggle script (themes/engine/scripts/
+# nomarchy-toggle-nightlight) writes both the toggle and the same
+# temperature value into state.json and flips the systemd unit for
+# instant feedback; the next rebuild's HM activation realigns systemd
+# with the persistent state.
+
 {
   services.hyprsunset = {
-    enable = lib.mkDefault true; # Always enabled, we control via IPC and state
-    extraArgs = lib.mkDefault [ "--temperature" temp ];
+    enable = lib.mkDefault config.nomarchy.toggles.nightlight;
+    extraArgs = lib.mkDefault [
+      "--temperature"
+      (toString config.nomarchy.nightlightTemperature)
+    ];
   };
 }

features/desktop/waybar/config/config.jsonc

@@ -5,7 +5,7 @@
   "spacing": 0,
   "height": 26,
   "modules-left": ["custom/nomarchy", "hyprland/workspaces"],
-  "modules-center": ["clock", "custom/update", "custom/voxtype", "custom/screenrecording-indicator", "custom/idle-indicator", "custom/notification-silencing-indicator"],
+  "modules-center": ["clock", "custom/update", "custom/screenrecording-indicator", "custom/idle-indicator", "custom/notification-silencing-indicator"],
   "modules-right": [
     "tray",
     "bluetooth",
@@ -43,7 +43,7 @@
     "format": "",
     "on-click": "nomarchy-menu",
     "on-click-right": "xdg-terminal-exec",
-    "tooltip-format": "Nomarchy Menu\n\nSuper + Alt + Space"
+    "tooltip-format": "Nomarchy Menu\n\nSuper + Shift + Space"
   },
   "custom/update": {
     "format": "",
@@ -58,12 +58,15 @@
     "interval": 5,
     "format": "󰍛",
     "on-click": "nomarchy-launch-or-focus-tui btop",
-    "on-click-right": "alacritty"
+    "on-click-right": "alacritty",
+    "tooltip-format": "Activity\n\nSuper + Ctrl + T"
   },
   "clock": {
     "format": "{:L%A %H:%M}",
     "format-alt": "{:L%d %B W%V %Y}",
-    "tooltip": false,
+    "tooltip": true,
+    "tooltip-format": "Show time\n\nSuper + Ctrl + Alt + T",
+    "on-click": "nomarchy-launch-or-focus-tui calcurse",
     "on-click-right": "nomarchy-launch-floating-terminal-with-presentation nomarchy-tz-select"
   },
   "network": {
@@ -72,9 +75,9 @@
     "format-wifi": "{icon}",
     "format-ethernet": "󰀂",
     "format-disconnected": "󰤮",
-    "tooltip-format-wifi": "{essid} ({frequency} GHz)\n⇣{bandwidthDownBytes}  ⇡{bandwidthUpBytes}",
-    "tooltip-format-ethernet": "⇣{bandwidthDownBytes}  ⇡{bandwidthUpBytes}",
-    "tooltip-format-disconnected": "Disconnected",
+    "tooltip-format-wifi": "{essid} ({frequency} GHz)\n⇣{bandwidthDownBytes}  ⇡{bandwidthUpBytes}\n\nSuper + Ctrl + W",
+    "tooltip-format-ethernet": "⇣{bandwidthDownBytes}  ⇡{bandwidthUpBytes}\n\nSuper + Ctrl + W",
+    "tooltip-format-disconnected": "Disconnected\n\nSuper + Ctrl + W",
     "interval": 3,
     "spacing": 1,
     "on-click": "nomarchy-launch-wifi"
@@ -89,8 +92,9 @@
       "default": ["󰁺", "󰁻", "󰁼", "󰁽", "󰁾", "󰁿", "󰂀", "󰂁", "󰂂", "󰁹"]
     },
     "format-full": "󰂅",
-    "tooltip-format-discharging": "{power:>1.0f}W↓ {capacity}%",
-    "tooltip-format-charging": "{power:>1.0f}W↑ {capacity}%",
+    "tooltip-format": "Battery Status\n\nSuper + Ctrl + Alt + B",
+    "tooltip-format-discharging": "{power:>1.0f}W↓ {capacity}%\n\nSuper + Ctrl + Alt + B",
+    "tooltip-format-charging": "{power:>1.0f}W↑ {capacity}%\n\nSuper + Ctrl + Alt + B",
     "interval": 5,
     "on-click": "nomarchy-menu power",
     "states": {
@@ -104,14 +108,14 @@
     "format-disabled": "󰂲",
     "format-connected": "󰂱",
     "format-no-controller": "",
-    "tooltip-format": "Devices connected: {num_connections}",
+    "tooltip-format": "Devices connected: {num_connections}\n\nSuper + Ctrl + B",
     "on-click": "nomarchy-launch-bluetooth"
   },
   "pulseaudio": {
     "format": "{icon}",
     "on-click": "nomarchy-launch-audio",
     "on-click-right": "pamixer -t",
-    "tooltip-format": "Playing at {volume}%",
+    "tooltip-format": "Playing at {volume}%\n\nSuper + Ctrl + A",
     "scroll-step": 5,
     "format-muted": "",
     "format-icons": {
@@ -138,19 +142,6 @@
     "signal": 10,
     "return-type": "json"
   },
-  "custom/voxtype": {
-    "exec": "nomarchy-voxtype-status",
-    "return-type": "json",
-    "format": "{icon}",
-    "format-icons": {
-      "idle": "",
-      "recording": "󰍬",
-      "transcribing": "󰔟"
-    },
-    "tooltip": true,
-    "on-click-right": "nomarchy-voxtype-config",
-    "on-click": "nomarchy-voxtype-model"
-  },
   "tray": {
     "icon-size": 12,
     "spacing": 17

features/desktop/waybar/config/style.css

@@ -97,12 +97,3 @@ tooltip {
 #custom-notification-silencing-indicator.active {
   color: #a55555;
 }
-
-#custom-voxtype {
-  min-width: 12px;
-  margin: 0 0 0 7.5px;
-}
-
-#custom-voxtype.recording {
-  color: #a55555;
-}

features/desktop/waybar/default.nix

@@ -37,14 +37,20 @@ let
 in
 {
   programs.waybar = {
-    enable = lib.mkDefault true;
-    systemd.enable = lib.mkDefault true;
+    # Gated on nomarchy.toggles.waybar — symmetric with services.hypridle
+    # (toggles.idle) and services.hyprsunset (toggles.nightlight). Disabled
+    # toggle means no waybar unit, so the bar stays hidden across rebuilds.
+    enable = lib.mkDefault config.nomarchy.toggles.waybar;
+    systemd.enable = lib.mkDefault config.nomarchy.toggles.waybar;
 
     settings = lib.mkDefault [ settings ];
     style = lib.mkDefault (builtins.readFile styleFile);
   };
 
-  home.packages = lib.mkDefault (with pkgs; [
+  # Not mkDefault: home.packages is a list other modules set at normal
+  # priority, so a mkDefault def is dropped — leaving font-awesome (waybar's
+  # icon font) uninstalled. Merge it in.
+  home.packages = with pkgs; [
     font-awesome
-  ]);
+  ];
 }

features/desktop/waybar/themes/catppuccin/style.css

@@ -1,2 +0,0 @@
-@define-color foreground #cdd6f4;
-@define-color background #181824;

features/desktop/waybar/themes/lumon/style.css

@@ -1,2 +0,0 @@
-@define-color foreground #d6e2ee;
-@define-color background #213442;

features/desktop/waybar/themes/nord/style.css

@@ -1,14 +0,0 @@
-@define-color background #2e3440;
-@define-color foreground #d8dee9;
-@define-color accent #88c0d0;
-
-/* Base style for Nord */
-* {
-  font-family: JetBrainsMono Nerd Font, FontAwesome;
-  font-size: 13px;
-}
-
-window#waybar {
-  background-color: @background;
-  color: @foreground;
-}

features/desktop/waybar/themes/retro-82/style.css

@@ -1,3 +0,0 @@
-@define-color bg #00172e;
-@define-color foreground #f6dcac;
-@define-color background alpha(@bg, 0.8);

features/desktop/waybar/themes/summer-day/config.jsonc

@@ -6,11 +6,10 @@
   "height": 60, 
   "layer": "top",
   "position": "top",
-  "output": "DP-2",
   "spacing": 15,
   "modules-left": ["custom/launcher", "clock", "clock#date"],
   "modules-center": ["wlr/workspaces"],
-  "modules-right": ["pulseaudio", "network", "battery", "custom/powermenu"],
+  "modules-right": ["custom/update", "pulseaudio", "network", "battery", "custom/powermenu"],
 
   "wlr/workspaces": {
       "disable-scroll": true,
@@ -35,12 +34,20 @@
   "custom/launcher": {
       "interval": "once",
       "format": "󰣇",
-      "on-click": "pkill wofi || wofi --show drun --term=kitty --width=20% --height=50% --columns 1 -I -s ~/.config/wofi/themes/everforest-light.css -o $MAIN_DISPLAY",
-      "tooltip": false
+      "on-click": "nomarchy-menu",
+      "tooltip-format": "Nomarchy Menu\n\nSuper + Shift + Space"
     },
 
+  "custom/update": {
+    "format": "",
+    "exec": "nomarchy-update-available",
+    "on-click": "nomarchy-launch-floating-terminal-with-presentation nomarchy-update",
+    "tooltip-format": "Nomarchy update available",
+    "signal": 7,
+    "interval": 21600
+  },
+
     "backlight": {
-      "device": "nvidia_0",
       "max-length": "4",
       "format": "{icon}",
       "tooltip-format": "{percent}%",
@@ -78,15 +85,17 @@
           "car": "",
           "default": ["", "", ""]
       },
-      "on-click-right": "pavucontrol",
-    "on-click": "pactl set-sink-mute @DEFAULT_SINK@ toggle"
+      "on-click": "nomarchy-launch-audio",
+      "on-click-right": "pamixer -t",
+      "tooltip-format": "Playing at {volume}%\n\nSuper + Ctrl + A"
   },
 
 "network": {
       "format-wifi": " {signalStrength}%",
       "format-ethernet": " {signalStrength}%",
       "format-disconnected": "󰤭",
-      "on-click": "sh ~/.config/wofi/scripts/wifimenu.sh"
+      "on-click": "nomarchy-launch-wifi",
+      "tooltip-format": "Wifi controls\n\nSuper + Ctrl + W"
 },
 
 "battery": {
@@ -105,20 +114,26 @@
     "format-plugged": " {capacity}%",
     "format-alt": "{icon} {capacity}%",
     "format-full": " 100%",
-    "format-icons": ["", "", "", "", "", "", "", "", "", ""]
+    "format-icons": ["", "", "", "", "", "", "", "", "", ""],
+    "tooltip-format": "Battery Status\n\nSuper + Ctrl + Alt + B"
 },
 
 "clock": {
-    "format": " {:%H:%M}"
+    "format": " {:%H:%M}",
+    "tooltip": true,
+    "tooltip-format": "Show time\n\nSuper + Ctrl + Alt + T"
 },
 
 "clock#date": {
-  "format": " {:%A, %B %d, %Y}"
+  "format": " {:%A, %B %d, %Y}",
+  "tooltip": true,
+  "tooltip-format": "Show time\n\nSuper + Ctrl + Alt + T",
+  "on-click": "nomarchy-launch-or-focus-tui calcurse"
 },
 
 "custom/powermenu": {
     "format": "",
-    "on-click": "pkill wofi || sh .config/wofi/scripts/powermenu.sh 'everforest-light' '--height=17% -o $MAIN_DISPLAY'",
+    "on-click": "nomarchy-menu power",
     "tooltip": false
   }
 }

features/desktop/waybar/themes/summer-night/config.jsonc

@@ -9,7 +9,7 @@
   "spacing": 15,
   "modules-left": ["custom/nomarchy", "clock", "clock#date"],
   "modules-center": ["hyprland/workspaces"],
-  "modules-right": [ "idle_inhibitor", "pulseaudio", "tray", "custom/powermenu"],
+  "modules-right": ["custom/update", "idle_inhibitor", "pulseaudio", "custom/battery", "tray", "custom/powermenu"],
 
   "hyprland/workspaces": {
       "disable-scroll": true,
@@ -40,7 +40,7 @@
       "interval": "once",
       "format": "\uf000",
       "on-click": "nomarchy-menu",
-      "tooltip-format": "Application Launcher"
+      "tooltip-format": "Nomarchy Menu\n\nSuper + Shift + Space"
     },
 
   "custom/update": {
@@ -73,20 +73,6 @@
     "return-type": "json"
   },
 
-  "custom/voxtype": {
-    "exec": "nomarchy-voxtype-status",
-    "return-type": "json",
-    "format": "{icon}",
-    "format-icons": {
-      "idle": "",
-      "recording": "󰍬",
-      "transcribing": "󰔟"
-    },
-    "tooltip": true,
-    "on-click-right": "nomarchy-voxtype-config",
-    "on-click": "nomarchy-voxtype-model"
-  },
-
     "backlight": {
       "max-length": "4",
       "format": "{icon} {percent}%",
@@ -130,37 +116,41 @@
       "on-click": "pamixer -t",
       "on-click-middle": "nomarchy-launch-audio",
       "on-click-right": "pavucontrol",
-      "tooltip-format": "{icon} {desc} | {volume}%"
+      "tooltip-format": "{icon} {desc} | {volume}%\n\nSuper + Ctrl + A"
   },
 
 "network": {
       "format-wifi": " {signalStrength}%",
       "format-ethernet": " {signalStrength}%",
       "format-disconnected": "󰤭",
-      "on-click": "nomarchy-launch-wifi"
+      "on-click": "nomarchy-launch-wifi",
+      "tooltip-format": "Wifi controls\n\nSuper + Ctrl + W"
 },
 
 "custom/battery": {
     "interval": 30,
     "format": "{}",
     "exec": "nomarchy-battery-status",
-    "on-click": "nomarchy-menu power"
+    "on-click": "nomarchy-menu power",
+    "tooltip-format": "Battery Status\n\nSuper + Ctrl + Alt + B"
 },
 
 "clock": {
     "format": " {:%H:%M}",
-    "tooltip": false
+    "tooltip": true,
+    "tooltip-format": "Show time\n\nSuper + Ctrl + Alt + T"
 },
 
 "clock#date": {
   "format": " {:%A, %B %d, %Y}",
-  "on-click": "kitty calcurse",
-  "tooltip-format": "Open calendar"
+  "tooltip": true,
+  "tooltip-format": "Show time\n\nSuper + Ctrl + Alt + T",
+  "on-click": "nomarchy-launch-or-focus-tui calcurse"
 },
 
 "custom/powermenu": {
     "format": "",
-    "on-click": "wlogout",
+    "on-click": "nomarchy-menu power",
     "tooltip": false
   }
 }

features/scripts/utils/nomarchy-build-iso

@@ -4,15 +4,8 @@ set -e
 # Build the Nomarchy Installer ISO declaratively using the flake.
 
 echo "Building Nomarchy Installer ISO..."
-
-# The output will be a symlink named 'result' in the current directory
 nix build .#nixosConfigurations.nomarchy-installer.config.system.build.isoImage
 
-if [ $? -eq 0 ]; then
-    ISO_PATH=$(readlink -f result/iso/*.iso)
-    echo "Success! ISO built at: $ISO_PATH"
-    echo "You can now burn this to a USB drive using 'dd' or 'etcher'."
-else
-    echo "Error: ISO build failed."
-    exit 1
-fi
+ISO_PATH=$(readlink -f result/iso/*.iso)
+echo "Success! ISO built at: $ISO_PATH"
+echo "You can now burn this to a USB drive using 'dd' or 'etcher'."

features/scripts/utils/nomarchy-build-live-iso

@@ -4,15 +4,8 @@ set -e
 # Build the Nomarchy Live ISO (Full Desktop Environment) using the flake.
 
 echo "Building Nomarchy Live ISO..."
-
-# The output will be a symlink named 'result' in the current directory
 nix build .#nixosConfigurations.nomarchy-live.config.system.build.isoImage
 
-if [ $? -eq 0 ]; then
-    ISO_PATH=$(readlink -f result/iso/*.iso)
-    echo "Success! Live ISO built at: $ISO_PATH"
-    echo "You can now burn this to a USB drive using 'dd' or 'etcher'."
-else
-    echo "Error: Live ISO build failed."
-    exit 1
-fi
+ISO_PATH=$(readlink -f result/iso/*.iso)
+echo "Success! Live ISO built at: $ISO_PATH"
+echo "You can now burn this to a USB drive using 'dd' or 'etcher'."

features/scripts/utils/nomarchy-docs-keybindings

@@ -1,110 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# nomarchy-docs-keybindings
-#
-# Regenerates docs/KEYBINDINGS.md from the Hyprland binding files. Run from the
-# repo root or anywhere — paths are resolved relative to this script.
-#
-#   nomarchy-docs-keybindings                       # write to stdout
-#   nomarchy-docs-keybindings --out docs/KEYBINDINGS.md
-#
-# Source files in render order. Each entry is "<repo-relative path>|<title>".
-
-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/clipboard.conf|Clipboard"
-  "core/home/config/nomarchy/default/hypr/bindings/media.conf|Media keys"
-  "features/desktop/hyprland/config/bindings.conf|Apps & web shortcuts"
-)
-
-prettify_key() {
-  case "$1" in
-    code:10) echo "1" ;; code:11) echo "2" ;; code:12) echo "3" ;;
-    code:13) echo "4" ;; code:14) echo "5" ;; code:15) echo "6" ;;
-    code:16) echo "7" ;; code:17) echo "8" ;; code:18) echo "9" ;;
-    code:19) echo "0" ;;
-    XF86AudioRaiseVolume)   echo "Volume Up" ;;
-    XF86AudioLowerVolume)   echo "Volume Down" ;;
-    XF86AudioMute)          echo "Mute" ;;
-    XF86AudioMicMute)       echo "Mic Mute" ;;
-    XF86AudioPlay)          echo "Play/Pause" ;;
-    XF86AudioStop)          echo "Stop" ;;
-    XF86AudioNext)          echo "Next Track" ;;
-    XF86AudioPrev)          echo "Previous Track" ;;
-    XF86MonBrightnessUp)    echo "Brightness Up" ;;
-    XF86MonBrightnessDown)  echo "Brightness Down" ;;
-    XF86KbdBrightnessUp)    echo "Kbd Brightness Up" ;;
-    XF86KbdBrightnessDown)  echo "Kbd Brightness Down" ;;
-    XF86KbdLightOnOff)      echo "Kbd Backlight" ;;
-    *) echo "$1" ;;
-  esac
-}
-
-trim() { sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//'; }
-
-render_section() {
-  local file="$1" title="$2"
-  [[ ! -f "$repo_root/$file" ]] && return
-  local rows
-  rows=$(grep -E '^[[:space:]]*bind[a-z]*[[:space:]]*=' "$repo_root/$file" || true)
-  [[ -z "$rows" ]] && return
-
-  local body=""
-  while IFS= read -r line; do
-    # Strip the "bindXXX =" prefix.
-    local rhs="${line#*=}"
-    local mods key desc
-    IFS=',' read -r mods key desc _ <<<"$rhs"
-    mods=$(printf '%s' "${mods:-}" | trim)
-    key=$(printf '%s'  "${key:-}"  | trim)
-    desc=$(printf '%s' "${desc:-}" | trim)
-    [[ -z "$desc" ]] && continue          # skip non-descriptive bindings
-    [[ -z "$mods" ]] && mods="—"
-    key=$(prettify_key "$key")
-    body+=$(printf '| %s | %s | %s |\n' "$mods" "$key" "$desc")
-    body+=$'\n'
-  done <<<"$rows"
-
-  [[ -z "$body" ]] && return
-
-  printf '\n## %s\n\n' "$title"
-  printf '_Source: `%s`_\n\n' "$file"
-  printf '| Modifiers | Key | Action |\n'
-  printf '| --- | --- | --- |\n'
-  printf '%s' "$body"
-}
-
-main() {
-  cat <<'HEADER'
-# Nomarchy Keybindings
-
-Auto-generated from the Hyprland binding files. **Do not edit by hand.**
-Re-run the generator after changing any `bindings/*.conf`:
-
-```bash
-./bin/utils/nomarchy-docs-keybindings --out docs/KEYBINDINGS.md
-```
-
-`SUPER` is the Meta / Win key. `code:NN` keys (X11 digit keycodes) are
-shown as the digit they correspond to. Media keys (`XF86Audio*`,
-`XF86MonBrightness*`, …) are prettified.
-HEADER
-  for entry in "${sources[@]}"; do
-    render_section "${entry%|*}" "${entry#*|}"
-  done
-}
-
-out=""
-if [[ "${1:-}" == "--out" ]]; then
-  out="${2:?--out needs a path}"; shift 2
-fi
-if [[ -n "$out" ]]; then
-  main >"$out"
-else
-  main
-fi

features/scripts/utils/nomarchy-docs-scripts

@@ -1,275 +0,0 @@
-#!/usr/bin/env bash
-set -e
-# Generator tolerates "no matches" exit codes from grep | sort.
-# pipefail and -e off; -u stays.
-set -u
-
-# nomarchy-docs-scripts
-#
-# Regenerates docs/SCRIPTS.md from the repo state. Produces:
-#   1. Header + status legend + regen instructions.
-#   2. Table of every nomarchy-* script (location, callers, status).
-#   3. Table of every menu entry in features/scripts/utils/nomarchy-menu
-#      (submenu, label, target command, status).
-#   4. Snapshot list of orphaned references (called somewhere, no script).
-#
-# Status heuristic in Phase A:
-#   kept     — file exists AND is called from at least one *.nix / *.conf /
-#              shell file outside its own directory.
-#   unused?  — file exists but no caller found. Phase B decides delete-dead
-#              vs intentional public API.
-#   missing  — referenced but no file. Phase B decides port-from-omarchy
-#              vs delete-dead vs stub-with-notify.
-#
-#   nomarchy-docs-scripts                       # write to stdout
-#   nomarchy-docs-scripts --out docs/SCRIPTS.md
-
-repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-cd "$repo_root"
-
-# --- Inventory -------------------------------------------------------------
-
-# Where scripts live, in render order.
-declare -A loc_label=(
-  ["features/scripts/utils"]="features/scripts/utils"
-  ["core/system/scripts"]="core/system/scripts"
-  ["themes/engine/scripts"]="themes/engine/scripts"
-)
-script_dirs=(features/scripts/utils core/system/scripts themes/engine/scripts)
-
-# Build name → location map (associative array of basename → repo-relative dir).
-declare -A script_loc
-for dir in "${script_dirs[@]}"; do
-  [[ -d "$dir" ]] || continue
-  while IFS= read -r f; do
-    script_loc["$(basename "$f")"]="$dir"
-  done < <(find "$dir" -maxdepth 1 -type f -name 'nomarchy-*')
-done
-
-# Find every nomarchy-* token referenced anywhere outside the script dirs.
-# (We exclude the script files themselves so they don't list themselves as
-# 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='*.json'
-  --include='*.toml' --include='*.ini' --include='*.lua'
-  --include='*.desktop' --include='*.txt' --include='*.sample'
-)
-search_dirs=(core features themes installer hosts bin lib README.md)
-
-# Files whose mentions of nomarchy-* are documentation about the scripts,
-# not real callers. Excluded from caller discovery so they don't promote
-# every script to `kept`.
-self_refs=(docs/SCRIPTS.md docs/ROADMAP.md docs/AGENT.md)
-
-ref_files_per_cmd() {
-  local cmd="$1"
-  local self_pattern
-  self_pattern=$(IFS='|'; echo "${self_refs[*]}")
-  grep -rlE "\\b${cmd}\\b" \
-    "${grep_includes[@]}" \
-    "${search_dirs[@]}" 2>/dev/null \
-    | grep -vE "^(features/scripts/utils|core/system/scripts|themes/engine/scripts)/${cmd}$" \
-    | grep -vE "^(${self_pattern})$" \
-    | sort -u
-}
-
-# All distinct nomarchy-* tokens we see anywhere in the repo.
-# 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 middle `grep -vE` drops lines where `nomarchy-*` is a derivation /
-# tmp file / sudoers basename / systemd unit / flake output / docker
-# container identifier — not a shell invocation — so they don't show up
-# as fake "missing" references.
-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 'docker[[:space:]]+[^|]*nomarchy-' \
-          | grep -oE 'nomarchy-[a-z0-9]([a-z0-9-]*[a-z0-9])?' \
-          | grep -vE '^(nomarchy-plymouth|nomarchy-sddm-theme|nomarchy-live|nomarchy-rev|nomarchy-windows)$' \
-          | sort -u)
-# The token-level denylist above 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` (a file written by the ISO), and
-# `nomarchy-windows` is a docker container name in compose heredocs.
-
-# --- Render: header --------------------------------------------------------
-
-main() {
-  cat <<'HEADER'
-# Nomarchy Script & Menu Audit
-
-Auto-generated table for [Pillar 3 of the roadmap](ROADMAP.md#3-pillar-script--menu-audit).
-**Do not edit by hand.** Regenerate after script or menu changes:
-
-```bash
-./bin/utils/nomarchy-docs-scripts --out docs/SCRIPTS.md
-```
-
-The status column uses a Phase A heuristic — `kept` / `unused?` / `missing`.
-Phase B (per-batch PRs) refines those into `port-from-omarchy`,
-`delete-dead`, or `stub-with-notify` and updates the rows.
-
-## Status legend
-
-- `kept` — script exists and is called from somewhere outside its own directory.
-- `unused?` — script exists but no caller was found. Could be dead, could be
-  intentional public API. Phase B triage decides.
-- `missing` — referenced from code but no script file exists. Phase B triage
-  decides whether to port from Omarchy upstream, delete the caller, or stub
-  with `notify-send`.
-- `port-from-omarchy` — Phase B verdict: lift the upstream Omarchy script,
-  rewrite for NixOS paths.
-- `delete-dead` — Phase B verdict: remove and update callers.
-- `stub-with-notify` — Phase B verdict: temporary `notify-send` stub.
-
-HEADER
-
-  # --- Render: scripts table ----------------------------------------------
-  printf '## Scripts (%d)\n\n' "${#script_loc[@]}"
-  printf '| Script | Location | Callers | Status | Notes |\n'
-  printf '| --- | --- | --- | --- | --- |\n'
-
-  # Sort scripts by name.
-  for name in $(printf '%s\n' "${!script_loc[@]}" | sort); do
-    local dir="${script_loc[$name]}"
-    local callers status callers_str
-    callers=$(ref_files_per_cmd "$name")
-    if [[ -z "$callers" ]]; then
-      status='`unused?`'
-      callers_str='—'
-    else
-      status='`kept`'
-      # Trim caller list to 2 entries + count.
-      local count
-      count=$(printf '%s\n' "$callers" | wc -l)
-      if (( count > 2 )); then
-        callers_str=$(printf '%s\n' "$callers" | head -2 | paste -sd, -)
-        callers_str="$callers_str, +$((count - 2)) more"
-      else
-        callers_str=$(printf '%s\n' "$callers" | paste -sd, -)
-      fi
-    fi
-    printf '| `%s` | `%s` | %s | %s |  |\n' \
-      "$name" "$dir" "$callers_str" "$status"
-  done
-  echo
-
-  # --- Render: missing references -----------------------------------------
-  printf '## Missing references\n\n'
-  printf 'Tokens grepped from `core/`, `features/`, `themes/`, `installer/`, `hosts/`, `bin/`, `lib/` that have no matching script file.\n\n'
-  printf '| Token | Referenced in | Status |\n'
-  printf '| --- | --- | --- |\n'
-  while IFS= read -r token; do
-    [[ -z "$token" ]] && continue
-    [[ -n "${script_loc[$token]:-}" ]] && continue
-    local refs
-    self_pattern=$(IFS='|'; echo "${self_refs[*]}")
-    refs=$(grep -rlE "\\b${token}\\b" \
-            "${grep_includes[@]}" \
-            "${search_dirs[@]}" 2>/dev/null \
-          | grep -vE "^(${self_pattern})$" \
-          | sort -u)
-    [[ -z "$refs" ]] && continue
-    local count refs_str
-    count=$(printf '%s\n' "$refs" | wc -l)
-    if (( count > 2 )); then
-      refs_str=$(printf '%s\n' "$refs" | head -2 | paste -sd, -)
-      refs_str="$refs_str, +$((count - 2)) more"
-    else
-      refs_str=$(printf '%s\n' "$refs" | paste -sd, -)
-    fi
-    printf '| `%s` | %s | `missing` |\n' "$token" "$refs_str"
-  done <<<"$all_refs"
-  echo
-
-  # --- Render: menu items -------------------------------------------------
-  printf '## Menu items\n\n'
-  printf 'Walked from `features/scripts/utils/nomarchy-menu`. Each `case` arm in a `show_*_menu` function becomes one row.\n\n'
-  printf '| Submenu | Entry | Calls | Status |\n'
-  printf '| --- | --- | --- | --- |\n'
-
-  awk '
-    /^show_[a-z_]+_menu\(\) {/ { sub(/\(\) {/, ""); current=$1; in_func=1; next }
-    /^[a-z_]+\(\) {/ && !/^show_/ { current=""; in_func=0; next }
-    /^}$/ { current=""; in_func=0; next }
-    !in_func { next }
-    /^  case \$\(menu / {
-      # extract the menu title between the first pair of double quotes
-      match($0, /menu "[^"]+" "[^"]+"/);
-      if (RSTART == 0) next;
-      title=substr($0, RSTART, RLENGTH);
-      # second quoted string is the option list
-      n=split(title, parts, "\"");
-      title=parts[2];
-      options=parts[4];
-      # split options on \n
-      split(options, opts, "\\\\n");
-      pending_submenu=current;
-      pending_title=title;
-      for (i=1;i<=length(opts);i++) pending_opts[i]=opts[i];
-      pending_count=length(opts);
-      next
-    }
-    /^  \*[A-Za-z]/ {
-      # case arm — extract pattern between the first * and the closing )
-      match($0, /\*[^)]*\)/);
-      if (RSTART == 0) next;
-      arm=substr($0, RSTART, RLENGTH);
-      gsub(/[*)]/, "", arm);
-      gsub(/^[[:space:]]+|[[:space:]]+$/, "", arm);
-      # action follows the )
-      rest=substr($0, RSTART+RLENGTH);
-      sub(/^[[:space:]]+/, "", rest);
-      sub(/[[:space:]]*;;[[:space:]]*$/, "", rest);
-      # match the first nomarchy-* token in the action
-      cmd=""
-      if (match(rest, /nomarchy-[a-z0-9-]+/)) {
-        cmd=substr(rest, RSTART, RLENGTH);
-      }
-      printf "%s|%s|%s\n", pending_submenu, arm, cmd;
-    }
-  ' features/scripts/utils/nomarchy-menu > /tmp/nomarchy-menu-rows.$$
-
-  while IFS='|' read -r submenu entry cmd; do
-    [[ -z "$entry" ]] && continue
-    [[ "$entry" =~ ^\) ]] && continue
-    status='`kept`'
-    if [[ -n "$cmd" ]]; then
-      if [[ -z "${script_loc[$cmd]:-}" ]]; then
-        status='`missing`'
-      fi
-    else
-      cmd='_(inline)_'
-    fi
-    printf '| `%s` | %s | `%s` | %s |\n' "$submenu" "$entry" "$cmd" "$status"
-  done < /tmp/nomarchy-menu-rows.$$
-  rm -f /tmp/nomarchy-menu-rows.$$
-  echo
-}
-
-out=""
-if [[ "${1:-}" == "--out" ]]; then
-  out="${2:?--out needs a path}"; shift 2
-fi
-if [[ -n "$out" ]]; then
-  main >"$out"
-else
-  main
-fi

features/scripts/utils/nomarchy-env-update

@@ -33,3 +33,4 @@ else
 fi
 
 echo "Environment update complete."
+nomarchy-hook post-update

features/scripts/utils/nomarchy-hyprland-monitor-scaling-cycle

@@ -22,4 +22,8 @@ esac
 hyprctl keyword misc:disable_scale_notification true
 hyprctl keyword monitor "$ACTIVE_MONITOR,${WIDTH}x${HEIGHT}@${REFRESH_RATE},auto,$NEW_SCALE"
 hyprctl keyword misc:disable_scale_notification false
+
+# Persist the choice declaratively
+nomarchy-state-write "hyprland.scale" "$NEW_SCALE"
+
 notify-send -u low "󰍹    Display scaling set to ${NEW_SCALE}x"

features/scripts/utils/nomarchy-hyprland-window-gaps-toggle

@@ -25,7 +25,6 @@ else
   hyprctl keyword general:border_size 0
 fi
 
-TMP_JSON=$(mktemp)
-jq --argjson state "$NEW_STATE" '.hyprland = $state' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
+nomarchy-state-write hyprland "$NEW_STATE" --type json
 
 echo "Toggled gaps to $NEW_STATE declaratively."

features/scripts/utils/nomarchy-hyprland-window-single-square-aspect-toggle

@@ -1,14 +1,16 @@
 #!/bin/bash
 set -e
 
-# Check current single_window_aspect_ratio setting
-CURRENT_VALUE=$(hyprctl getoption "layout:single_window_aspect_ratio" 2>/dev/null | head -1)
+# single_window_aspect_ratio lives under the dwindle namespace (the default
+# layout), not a bare `layout:` — `hyprctl getoption layout:…` returns
+# "no such option" and the keyword set is silently dropped.
+CURRENT_VALUE=$(hyprctl getoption "dwindle:single_window_aspect_ratio" 2>/dev/null | head -1)
 
 # Parse vec2 output: "vec2: [1, 1]" or "vec2: [0, 0]"
 if [[ $CURRENT_VALUE == *"[1, 1]"* ]]; then
-  hyprctl keyword layout:single_window_aspect_ratio "0 0"
+  hyprctl keyword dwindle:single_window_aspect_ratio "0 0"
   notify-send -u low "    Disable single-window square aspect ratio"
 else
-  hyprctl keyword layout:single_window_aspect_ratio "1 1"
+  hyprctl keyword dwindle:single_window_aspect_ratio "1 1"
   notify-send -u low "    Enable single-window square aspect"
 fi

features/scripts/utils/nomarchy-hyprland-workspace-layout-toggle

@@ -1,15 +1,19 @@
 #!/bin/bash
 set -e
 
-# Toggle the layout on the current active workspace between dwindle and scrolling
+# Toggle the tiling layout between Hyprland's two built-in layouts, dwindle
+# and master. (The old version read `.tiledLayout` off `hyprctl
+# activeworkspace -j` and switched to "scrolling" — but that field doesn't
+# exist, so the read was always null, and "scrolling" isn't a real layout
+# (`hyprctl layouts` only lists dwindle/master), so the toggle silently
+# did nothing.)
 
-ACTIVE_WORKSPACE=$(hyprctl activeworkspace -j | jq -r '.id')
-CURRENT_LAYOUT=$(hyprctl activeworkspace -j | jq -r '.tiledLayout')
+CURRENT_LAYOUT=$(hyprctl getoption general:layout -j | jq -r '.str')
 
 case "$CURRENT_LAYOUT" in
-  dwindle) NEW_LAYOUT=scrolling ;;
+  dwindle) NEW_LAYOUT=master ;;
   *) NEW_LAYOUT=dwindle ;;
 esac
 
-hyprctl keyword workspace $ACTIVE_WORKSPACE, layout:$NEW_LAYOUT
+hyprctl keyword general:layout "$NEW_LAYOUT"
 notify-send -u low "󱂬    Workspace layout set to $NEW_LAYOUT"

features/scripts/utils/nomarchy-installed-summary

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+set -e
+
+# Print a curated "what the installer wrote" summary so the user can verify
+# the system shape on first boot before they start customising. Reads from
+# state.json where the schema persists the value, and falls back to live
+# introspection for things the schema doesn't track (form factor, drives,
+# active software profiles, FDE).
+#
+# Invoked as Step 0 of nomarchy-welcome and available as a standalone CLI.
+
+HOME_STATE="$HOME/.config/nomarchy/state.json"
+SYS_STATE="/etc/nixos/state.json"
+
+jq_or_empty() {
+    local file="$1"
+    local query="$2"
+    [[ -f "$file" ]] || { echo ""; return; }
+    jq -r "$query // empty" "$file" 2>/dev/null || echo ""
+}
+
+theme=$(jq_or_empty "$HOME_STATE" '.theme')
+font=$(jq_or_empty "$HOME_STATE" '.font')
+panel=$(jq_or_empty "$HOME_STATE" '.panelPosition')
+tz=$(jq_or_empty "$SYS_STATE" '.timezone')
+dns=$(jq_or_empty "$SYS_STATE" '.dns')
+hybrid_gpu=$(jq_or_empty "$SYS_STATE" '.features.hybridGPU')
+
+# Form factor: battery presence (same signal the installer uses to auto-set
+# nomarchy.{system.,}formFactor). `compgen` is a bash programmable-completion
+# builtin, and the non-interactive bash this script gets wrapped with is
+# compiled without it — so a glob into a nullglob array, not `compgen -G`.
+shopt -s nullglob
+batteries=( /sys/class/power_supply/BAT* )
+shopt -u nullglob
+if (( ${#batteries[@]} )); then
+    form_factor="laptop"
+else
+    form_factor="desktop"
+fi
+
+# Active software profiles: heuristic detection. The installer bakes the
+# user's pick into the generated home.nix as concrete `home.packages` /
+# system toggles rather than persisting a profile list, so we check for
+# the marker package of each profile.
+profiles=()
+command -v docker >/dev/null 2>&1 && profiles+=("Dev")
+command -v steam  >/dev/null 2>&1 && profiles+=("Gaming")
+command -v libreoffice >/dev/null 2>&1 && profiles+=("Office")
+command -v obs >/dev/null 2>&1 && profiles+=("Media")
+command -v rg >/dev/null 2>&1 && profiles+=("CLI Utils")
+
+profiles_str="None"
+if (( ${#profiles[@]} > 0 )); then
+    profiles_str="$(IFS=', '; echo "${profiles[*]}")"
+fi
+
+# FDE: any crypt device present means the install used LUKS.
+luks="No"
+if lsblk -no TYPE 2>/dev/null | grep -q '^crypt$'; then
+    luks="Yes"
+fi
+
+# Drives: target disks + their mounted root/boot/crypt partitions. Filter
+# noise (loop/rom/zram) so the table reads like an install receipt.
+drives=$(lsblk -no NAME,SIZE,TYPE,MOUNTPOINT 2>/dev/null \
+    | grep -Ev '^(loop|sr|zram)' \
+    | awk 'NF>=3 && $3 ~ /^(disk|part|crypt)$/' \
+    || true)
+
+version_line=$(nomarchy-version 2>/dev/null || echo "Nomarchy")
+hostname_line="$(hostname 2>/dev/null || echo "")"
+
+# Render via gum format (markdown). Fallback to plain text when gum isn't
+# on PATH — keeps the script callable from minimal contexts like recovery.
+render() {
+    cat <<MD
+# $version_line on \`$hostname_line\`
+
+| Setting       | Value             |
+| ---           | ---               |
+| Theme         | ${theme:-—}       |
+| Font          | ${font:-—}        |
+| Panel         | ${panel:-—}       |
+| Form factor   | $form_factor      |
+| Timezone      | ${tz:-—}          |
+| DNS           | ${dns:-—}         |
+| Hybrid GPU    | ${hybrid_gpu:-false} |
+| Profiles      | $profiles_str     |
+| FDE (LUKS)    | $luks             |
+
+## Drives
+
+\`\`\`
+$drives
+\`\`\`
+MD
+}
+
+if command -v gum >/dev/null 2>&1; then
+    render | gum format
+else
+    render
+fi

features/scripts/utils/nomarchy-launch-screensaver

@@ -13,7 +13,7 @@ pgrep -f org.nomarchy.screensaver && exit 0
 
 # Allow screensaver to be turned off but also force started
 # Skip if screensaver is disabled in configuration
-if [[ $NNOMARCHY_TOGGLE_SCREENSAVER == "false" ]] && [[ $1 != "force" ]]; then
+if [[ $NOMARCHY_TOGGLE_SCREENSAVER == "false" ]] && [[ $1 != "force" ]]; then
   exit 0
 fi