feat: implement hybrid declarative state with automatic Nix sync

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