Nomarchy/README.md

# 👑 Nomarchy

**Nomarchy** is a professional-grade NixOS distribution that ships a highly curated Hyprland desktop on a strictly declarative, flake-based foundation. It provides a highly polished, "it just works" experience for power users who want a beautiful Wayland environment without sacrificing the reliability of NixOS.

## ✨ Key Features

- **Purely Declarative:** Your entire desktop—themes, fonts, wallpapers, and toolchains—is defined in code.
- **Modular Merging Architecture:** Distro code and user code are strictly separated. You can update the distro core without ever touching or breaking your personal configurations.
- **Interactive "Smart" Installer:** Detects hardware, sets up networking, localizes timezones/keymaps, and offers multi-select software profiles.
- **Erase Your Darlings (Optional):** Optional BTRFS root-wipe on boot ensures your system stays pristine and 100% declarative.
- **Dynamic Theming Engine:** 20+ built-in themes with instant UI feedback via IPC (swww, waybar, and stylix).
- **Portable State (`nomarchy-sync`):** Easily backup and sync your declarative config and dynamic state (theme/wallpaper choices) to a private Git repo.

---

## 📂 Component-Based Architecture

Nomarchy uses a **Feature-Centric Directory Structure**. For a comprehensive breakdown of the system architecture, folder roles, and module logic, see the [Detailed Architecture Documentation](docs/STRUCTURE.md).

Configuration, modules, and utilities are strictly organized to maintain sanity as the system grows.

- **`core/`**: Foundational OS & User defaults (Bootloader, Audio, Bluetooth, core system features).
- **`features/`**: Isolated modules containing Nix logic and raw dotfiles.
  - **`features/apps/`**: App-specific configs (e.g., `features/apps/btop/`, `features/apps/kitty/`), each containing their own `default.nix` and standalone `config/` directory mapped via Home Manager.
  - **`features/desktop/`**: Desktop environment components (e.g., Hyprland, Waybar).
  - **`features/scripts/utils/`**: Consolidated repository for all custom Nomarchy bash scripts, centrally packaged and injected into the user's `PATH` with correct dependencies.
- **`themes/`**: The global theming engine. It holds pure color data and logic. *Theme-specific app layouts* (like a custom Waybar layout) are stored directly inside the app's feature folder, solving the matrix problem of theming.

---

## 📥 Installation

### 1. Try it in a VM (Recommended)
Verify the experience without touching your hardware:
```bash
./bin/utils/nomarchy-test-installer
```
This builds a full graphical VM of the installer environment. Once inside, click the **Install Nomarchy** icon or run `nomarchy-install`.

### 2. Build the Installer ISO
To install on physical hardware, generate your own bootable image:
```bash
./features/scripts/utils/nomarchy-build-iso       # Minimal TTY installer
./features/scripts/utils/nomarchy-build-live-iso  # Graphical try-before-install
```
The ISO will be located at `./result/iso/nixos-*.iso`. Flash it to a USB drive and boot.

### 3. Run the Installer
Once booted into the Live environment, launch the installer:
```bash
nomarchy-install
```
The wizard will guide you through:
- **Networking:** An interactive wizard to connect to Wi-Fi if needed.
- **Hardware:** Optimized profiles for Dell XPS, Framework, Apple T2, and more.
- **Storage:** Choice between Standard Ext4 or Encrypted BTRFS with optional **Impermanence**.
- **Localization:** Searchable timezones and keyboard layout selection.

### Already on NixOS?
Layer Nomarchy onto an existing 25.11 install without reformatting — see the [Migration Guide](docs/MIGRATION.md).

---

## 🛠️ Configuration & Usage

Nomarchy uses a "Downstream" model. After installation, your configuration lives in `/etc/nixos/` and is split into three main parts:

### 1. Distro Core (Upstream)
Managed via the public Git repository. This is the engine. You should generally not modify files here.

### 2. Your System (`system.nix`)
Add system-wide packages, services, and hardware tweaks here.
*Example: Adding a persistent directory for Docker if using Impermanence:*
```nix
environment.persistence."/persist" = {
  directories = [ "/var/lib/docker" ];
};
```

### 3. Your User Environment (`home.nix`)
Add user-level packages, aliases, and dotfiles here.
*Example: Overriding the default terminal:*
```nix
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).

### 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:

```bash
sys-update  # Rebuilds the NixOS system (Runs: sudo nixos-rebuild switch --flake .#default --impure)
env-update  # Reloads your Home Manager environment (Runs: home-manager switch --flake .#default --impure)
```

---

## 🚀 Commands & Keybindings

The full list lives in [`docs/KEYBINDINGS.md`](docs/KEYBINDINGS.md) (auto-generated from the Hyprland configs). A few highlights:

| Keybinding | Action |
| :--- | :--- |
| `Super + Space` | **App Launcher** (Walker) |
| `Super + Shift + Space` | **Nomarchy Menu** (Walker) |
| `Super + Alt + Space` | **Toggle Top Bar** (Waybar) |
| `Super + Return` | Open Terminal |
| `Super + Q` | Close Window |

### Utility Scripts
Nomarchy includes dozens of productivity scripts available in your PATH. Some highlights:
- `nomarchy-sync push <repo>`: Backup your setup to Git.
- `nomarchy-theme-bg-next`: Cycle to the next wallpaper in the current theme.
- `nomarchy-menu`: The central hub for all utilities and pickers.

---
*Built with ❤️ using NixOS, Hyprland, Stylix, and the Nomarchy Community.*