feat: implement hybrid declarative state with automatic Nix sync

core/home/options.nix

@@ -88,35 +88,44 @@ in
     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".
+          or a numeric string like "1", "1.25", "1.5", "2". Driven
+          by the declarative state.
         '';
       };
     };

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."
 

docs/AGENT.md

@@ -201,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/MIGRATION.md

@@ -122,6 +122,12 @@ 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; [
     firefox
     xfce.thunar
@@ -144,9 +150,17 @@ create minimal versions to start:
 }
 ```
 
+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

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.
 
 ---
 

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-state-write

@@ -99,3 +99,11 @@ LOCK_FILE="${STATE_FILE}.lock"
 
 # Clean up lock file
 rm -f "$LOCK_FILE"
+
+# If we just updated the main home state file, sync it to the Nix configuration.
+# This bridges the gap between runtime UI changes and declarative Nix.
+if [[ "$STATE_FILE" == "$HOME/.config/nomarchy/state.json" ]]; then
+    if command -v nomarchy-sync-nix-state >/dev/null 2>&1; then
+        nomarchy-sync-nix-state
+    fi
+fi

features/scripts/utils/nomarchy-sync-nix-state

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+set -e
+
+# Nomarchy Nix State Sync
+# Bridges the gap between runtime UI changes (state.json) and declarative
+# Nix configuration (nomarchy-state.nix).
+
+STATE_JSON="$HOME/.config/nomarchy/state.json"
+NIX_STATE_FILE="/etc/nixos/nomarchy-state.nix"
+
+# If state.json is missing, nothing to sync
+if [ ! -f "$STATE_JSON" ]; then
+    exit 0
+fi
+
+# Determine destination.
+# If we are in the repo, we sync to ./nomarchy-state.nix (dev mode).
+# Otherwise, we sync to /etc/nixos/nomarchy-state.nix (real install).
+if [ -f "flake.nix" ] || [ -d ".git" ]; then
+    DEST="./nomarchy-state.nix"
+elif [ -w "/etc/nixos" ]; then
+    DEST="$NIX_STATE_FILE"
+else
+    # Nowhere to sync to
+    exit 0
+fi
+
+# Generate the Nix attribute set from JSON.
+# We use jq to extract the keys and format them as Nix assignments.
+# Note: font in state.json maps to fonts.monospace in Nix.
+
+{
+    echo "# DO NOT EDIT MANUALLY - Managed by Nomarchy scripts."
+    echo "# This file mirrors your UI choices (theme, font, etc.) into the declarative"
+    echo "# Nix configuration. It is imported by your home.nix."
+    echo "{"
+    echo "  nomarchy = {"
+
+    # Core UI strings
+    echo "    theme = \"$(jq -r '.theme // empty' "$STATE_JSON")\";"
+    echo "    fonts.monospace = \"$(jq -r '.font // empty' "$STATE_JSON")\";"
+    echo "    panelPosition = \"$(jq -r '.panelPosition // empty' "$STATE_JSON")\";"
+    echo "    wallpaper = \"$(jq -r '.wallpaper // empty' "$STATE_JSON")\";"
+
+    # Hyprland layout (numbers)
+    echo "    hyprland = {"
+    echo "      scale = \"$(jq -r '.hyprland.scale // "auto"' "$STATE_JSON")\";"
+    echo "      gaps_in = $(jq -r '.hyprland.gaps_in // 5' "$STATE_JSON");"
+    echo "      gaps_out = $(jq -r '.hyprland.gaps_out // 10' "$STATE_JSON");"
+    echo "      border_size = $(jq -r '.hyprland.border_size // 2' "$STATE_JSON");"
+    echo "    };"
+
+    # Toggles (booleans)
+    echo "    toggles = {"
+    echo "      suspend = $(jq -r '.suspend // true' "$STATE_JSON");"
+    echo "      screensaver = $(jq -r '.screensaver // true' "$STATE_JSON");"
+    echo "      idle = $(jq -r '.idle // true' "$STATE_JSON");"
+    echo "      nightlight = $(jq -r '.nightlight // false' "$STATE_JSON");"
+    echo "      waybar = $(jq -r '.waybar // true' "$STATE_JSON");"
+    echo "    };"
+
+    echo "  };"
+    echo "}"
+} > "$DEST.tmp"
+
+# Final atomic move
+mv "$DEST.tmp" "$DEST"

features/scripts/utils/nomarchy-toggle-screensaver

@@ -19,8 +19,7 @@ else
     notify-send -u low "   Screensaver disabled"
 fi
 
-TMP_JSON=$(mktemp)
-jq --argjson val "$NEW_VALUE" '.screensaver = $val' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
+nomarchy-state-write screensaver "$NEW_VALUE" --type bool
 
 echo "Screensaver state set to $NEW_VALUE. Updating environment..."
 

features/scripts/utils/nomarchy-toggle-waybar

@@ -22,7 +22,6 @@ else
     notify-send -u low "  Top bar disabled"
 fi
 
-TMP_JSON=$(mktemp)
-jq --argjson val "$NEW_VALUE" '.waybar = $val' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
+nomarchy-state-write waybar "$NEW_VALUE" --type bool
 
 echo "Waybar state set to $NEW_VALUE."

features/scripts/utils/nomarchy-welcome

@@ -61,13 +61,10 @@ echo "Step 4: Choose your monitor scaling"
 echo "Recommended: 'auto' for most screens, '2' for 4K/HiDPI."
 SCALE=$(gum choose "auto" "1" "1.25" "1.5" "2")
 if [[ -n "$SCALE" ]]; then
-    # Write to nested hyprland.scale key
-    STATE_DIR="$HOME/.config/nomarchy"
-    mkdir -p "$STATE_DIR"
-    TMP_FILE=\$(mktemp)
-    jq ".hyprland.scale = \"$SCALE\"" "\$STATE_FILE" > "\$TMP_FILE" && mv "\$TMP_FILE" "\$STATE_FILE"
+    nomarchy-state-write "hyprland.scale" "$SCALE"
 fi
 
+
 # Skip system-modifying steps in the Live ISO environment
 if [[ "$USER" == "nixos" ]]; then
     echo ""

installer/install.sh

@@ -1714,6 +1714,12 @@ EOF
     cat > /mnt/etc/nixos/home.nix << EOF
 { pkgs, ... }:
 {
+  imports = [
+    # Machine-managed state (theme, font, toggles).
+    # UI scripts update this file automatically.
+    ./nomarchy-state.nix
+  ];
+
   # Physical form factor — mirrors nomarchy.system.formFactor in system.nix.
   # Gates UI affordances like the waybar battery widget.
   nomarchy.formFactor = "$FORM_FACTOR";
@@ -1854,6 +1860,45 @@ EOF
             state = schema.system // { timezone = \"$_state_tz\"; };
           in builtins.toJSON state
         " | nrun jq '.' > /mnt/etc/nixos/state.json
+
+    # nomarchy-state.nix — the declarative counterpart to state.json.
+    # Imported by home.nix so UI changes are solidified in code.
+    # Generated from lib/state-schema.nix's home block.
+    nix --extra-experimental-features 'nix-command flakes' eval \
+        --impure --raw \
+        --expr "
+          let
+            flake = builtins.getFlake \"$NOMARCHY_REPO\";
+            lib = flake.inputs.nixpkgs.lib;
+            schema = import \"$NOMARCHY_REPO/lib/state-schema.nix\" { inherit lib; };
+            s = schema.home;
+          in ''
+            # DO NOT EDIT MANUALLY - Managed by Nomarchy scripts.
+            # This file mirrors your UI choices (theme, font, etc.) into the declarative
+            # Nix configuration. It is imported by your home.nix.
+            {
+              nomarchy = {
+                theme = \"\${s.theme}\";
+                fonts.monospace = \"\${s.font}\";
+                panelPosition = \"\${s.panelPosition}\";
+                wallpaper = \"\${s.wallpaper}\";
+                hyprland = {
+                  scale = \"\${s.hyprland.scale}\";
+                  gaps_in = \${toString s.hyprland.gaps_in};
+                  gaps_out = \${toString s.hyprland.gaps_out};
+                  border_size = \${toString s.hyprland.border_size};
+                };
+                toggles = {
+                  suspend = \${lib.boolToString s.suspend};
+                  screensaver = \${lib.boolToString s.screensaver};
+                  idle = \${lib.boolToString s.idle};
+                  nightlight = \${lib.boolToString s.nightlight};
+                  waybar = \${lib.boolToString s.waybar};
+                };
+              };
+            }
+          ''
+        " > /mnt/etc/nixos/nomarchy-state.nix
 }
 
 # ============================================================================

themes/engine/scripts/nomarchy-font-set

@@ -24,14 +24,8 @@ mkdir -p "$STATE_DIR"
 [[ ! -f $STATE_FILE ]] && echo "{}" > "$STATE_FILE"
 
 if fc-list | grep -iq "$font_name"; then
-  TMP_JSON=$(mktemp)
-  jq --arg font "$font_name" '.font = $font' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
-  echo "Font set to $font_name."
-  echo "NOTE: This change is TEMPORARY and will be lost on the next system rebuild."
-  echo "To make this font permanent, add the following to your /etc/nixos/home.nix:"
-  echo "  nomarchy.fonts.monospace = \"$font_name\";"
-  echo ""
-  echo "Applying changes with nomarchy-env-update..."
+  nomarchy-state-write font "$font_name"
+  echo "Font set to $font_name. Applying changes with nomarchy-env-update..."
 
   if [[ "$no_update" == "true" ]]; then
     echo "Skipping nomarchy-env-update due to --no-update flag."

themes/engine/scripts/nomarchy-theme-bg-next

@@ -45,8 +45,7 @@ done
 NEXT_INDEX=$(((INDEX + 1) % TOTAL))
 NEW_BG="$BG_DIR/${BACKGROUNDS[$NEXT_INDEX]}"
 
-TMP_JSON=$(mktemp)
-jq --arg wp "$NEW_BG" '.wallpaper = $wp' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
+nomarchy-state-write wallpaper "$NEW_BG"
 
 # Instant feedback via swww
 if pgrep -x swww-daemon >/dev/null; then

themes/engine/scripts/nomarchy-theme-bg-set

@@ -28,8 +28,7 @@ mkdir -p "$STATE_DIR"
 [[ ! -f $STATE_FILE ]] && echo "{}" > "$STATE_FILE"
 
 # Persist the choice for the next rebuild.
-TMP_JSON=$(mktemp)
-jq --arg wp "$BACKGROUND" '.wallpaper = $wp' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
+nomarchy-state-write wallpaper "$BACKGROUND"
 
 # Create symlink to the new background
 ln -nsf "$BACKGROUND" "$CURRENT_BACKGROUND_LINK"

themes/engine/scripts/nomarchy-theme-set

@@ -34,13 +34,12 @@ if [ ! -d "$THEMES_DIR/$THEME_NAME" ]; then
   exit 1
 fi
 
-TMP_JSON=$(mktemp)
-jq --arg theme "$THEME_NAME" '.theme = $theme' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
+nomarchy-state-write theme "$THEME_NAME"
 
 # Sync to system state if we have permissions (for system-level theming like browser policies)
 SYSTEM_STATE_FILE="/etc/nixos/state.json"
 if [ -w "$SYSTEM_STATE_FILE" ] || [ -w "/etc/nixos" ]; then
-    tmp=$(mktemp); sudo jq --arg theme "$THEME_NAME" '.theme = $theme' "$SYSTEM_STATE_FILE" > "$tmp" 2>/dev/null && sudo mv "$tmp" "$SYSTEM_STATE_FILE" 2>/dev/null || rm -f "$tmp"
+    nomarchy-state-write --file "$SYSTEM_STATE_FILE" theme "$THEME_NAME"
 fi
 
 # Try to find a background for this theme
@@ -48,17 +47,11 @@ BG_DIR="$THEMES_DIR/$THEME_NAME/backgrounds"
 if [ -d "$BG_DIR" ]; then
   BG=$(ls "$BG_DIR" | head -n 1)
   if [ -n "$BG" ]; then
-    TMP_JSON=$(mktemp)
-    jq --arg wp "$BG_DIR/$BG" '.wallpaper = $wp' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
+    nomarchy-state-write wallpaper "$BG_DIR/$BG"
   fi
 fi
 
-echo "Theme set to $THEME_NAME."
-echo "NOTE: This change is TEMPORARY and will be lost on the next system rebuild."
-echo "To make this theme permanent, add the following to your /etc/nixos/home.nix:"
-echo "  nomarchy.theme = \"$THEME_NAME\";"
-echo ""
-echo "Applying changes with nomarchy-env-update..."
+echo "Theme set to $THEME_NAME. Applying changes with nomarchy-env-update..."
 
 if [[ "$NO_UPDATE" == "true" ]]; then
   echo "Skipping nomarchy-env-update due to --no-update flag."

themes/engine/scripts/nomarchy-toggle-nightlight

@@ -25,7 +25,6 @@ else
     notify-send -u low "  Nightlight disabled"
 fi
 
-TMP_JSON=$(mktemp)
-jq --argjson val "$NEW_VALUE" '.nightlight = $val' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
+nomarchy-state-write nightlight "$NEW_VALUE" --type bool
 
 echo "Nightlight state set to $NEW_VALUE."