# Nomarchy - A NixOS-based distribution with Omarchy flavour - Agent Build Blueprint

## System Architecture Overview
Nomarchy uses a **Modular Merging Architecture**. The distro is distributed as a Nix Flake that exports two primary modules: `nixosModules.system` and `nixosModules.home`. This approach ensures strict separation between the "Upstream" core and the "Downstream" user configuration.

Users interact with the system by importing the distro's modules into their own `flake.nix` and then layering their own personal modules (`system.nix` and `home.nix`) on top. This follows the native NixOS design pattern for declarative, multi-module systems.

## Directory Structure
* `flake.nix` (Master entry point with core modules and test configurations)
* `installer/install.sh` (Interactive installer generating a clean downstream flake)
* `modules/system/default.nix` (Distro-wide OS defaults: SDDM, Plymouth, Audio, Network)
* `modules/home/default.nix` (Distro-wide user environment: Hyprland, Waybar, Styling)
* `bin/` (The collection of Omarchy productivity and config scripts)
* `themes/` (Distro-wide color palettes and backgrounds)

## Core Components & Logic

### 1. Separation of Concerns (Upstream vs. Downstream)
* **Upstream:** The `nomarchy/` directory contains the core logic. It is treated as an immutable input by the target system.
* **Downstream:** The user's `/etc/nixos/flake.nix` imports the upstream modules. The user's personal customizations are kept in `/etc/nixos/system.nix` and `/etc/nixos/home.nix`.
* **Merging:** NixOS automatically merges definitions. For example, if both the distro and the user add packages to `home.packages`, the final system includes the union of both lists.

### 2. The Interactive Installer (`installer/install.sh`)
The installer is designed to bootstrap a fresh system with this modular structure:
1.  **Repo Detection:** Identifies the location of the Nomarchy source.
2.  **Scaffolding:** Creates a new downstream `flake.nix` that imports Nomarchy core modules.
3.  **User Files:** Generates skeleton `system.nix` and `home.nix` files for the user to customize.
4.  **Flake Updates:** Uses the public Git repository as the upstream source, allowing users to update their system via `nix flake update`.

### 3. Home Manager Integration
* **Hybrid Declarative State:** While the distro is declarative, it uses state files in `~/.config/home-manager/` (managed by the distro's scripts) to allow for instant UI feedback (theming, fonts, wallpapers) without needing a full system rebuild for every small tweak.
* **Script Wrapping:** All scripts in `bin/` are wrapped with their specific dependencies (`swayosd`, `pulseaudio`, `jq`, etc.) to ensure they work reliably across different hardware.

### 4. Dynamic Theming
* **Palettes:** Themes are defined in simple `colors.toml` files. The distro dynamically generates Base16 palettes from these, allowing for infinite theme expansion without modifying Nix code.

## Verification & Build
*   **Test Installer:** `./bin/utils/nomarchy-test-installer` (Builds a VM of the installer environment).
*   **Check Integrity:** `nix flake check --impure` (Verifies all configurations evaluate).
*   **Build ISO:** `nix build .#nixosConfigurations.installerIso.config.system.build.isoImage` (Generates the flashable USB image).