# Goals — what "done" looks like for Nomarchy

The north star every loop iteration serves. When two options conflict,
the earlier pillar wins.

## The four pillars (in priority order)

1. **Rock-stable.** A workstation you never fight. Everything is a NixOS/HM
   generation — atomic, rollbackable, never partial. `nix flake check` is
   green at every commit on `main`. Regressions are caught by the VM-test
   suite (`checks.*`), not by users. `v1` only ever advances after human
   on-hardware QA.
2. **Reproducible, with zero hidden state.** The downstream flake checkout
   *is* the machine. All user-settable config is menu-writable into the
   git-tracked state file (`theme-state.json` `settings.*`) — never
   `~/.local/state`, never `~/.config` side files. Re-cloning your flake
   reproduces the machine, settings and all.
3. **Effortless to configure.** The user never has to learn Nix. Every
   common knob is reachable from `nomarchy-menu` (SUPER+M); the menu is an
   ergonomic writer for the flake. Where a toggle can take effect without a
   rebuild, it must (`--no-switch` + flip the running service).
4. **Beautiful.** One JSON themes the entire desktop coherently — Hyprland,
   Waybar, Ghostty, btop, rofi, GTK/Qt, boot splash, greeter. Every new
   surface follows the palette. Informative, self-gating Waybar modules
   (they hide when irrelevant). No unthemed corner survives contact with
   the theme switcher.

## Quality bars (non-negotiable)

- **The honesty rule** (docs/TESTING.md): for anything visual, "the Nix
  evaluates" is not "it renders". Verify at the highest tier you can reach
  (see LOOP.md's verification ladder) and *state the tier you reached*.
  Never claim a check you didn't run.
- **Parity rule:** any module added to the generated Waybar config must
  also be added to the summer-day/night `waybar.jsonc` whole-swaps.
- **Menu placement:** new menu entries go in the right category submenu
  (Tools › / System ›), with a direct `SUPER+CTRL+<mnemonic>` bind and
  self-gating where applicable. The root picker stays six entries.
- **Opt-in features** ship a commented example in
  `templates/downstream/{home,system}.nix`.
- **Option surface discipline:** a toggle exists only when there is real
  config behind it. Bare package installs go in the template's
  `home.packages` (opt-out = delete the line), never a `nomarchy.apps.*`.

## Non-goals (do not drift into these)

- **No binary cache.** Compile-from-source is a deliberate values call;
  automation targets the config/lock channel, not artifact distribution.
- **No second theming pipeline.** The dispatcher owns menu structure; the
  renderer (rofi) stays swappable. No GTK4 launcher.
- **No nixpkgs major bump on `main`.** Lock updates stay within the pinned
  release branch; a release jump is a deliberate `v2`, hand-edited by the
  maintainer (the last attempt was discarded over a Hyprland OOM — see
  agent/MEMORY.md).
- **No repo-wide reformat.** The `.nix` files use deliberate aligned
  hand-formatting; adopting a formatter is an open maintainer decision
  (BACKLOG.md § Decisions), not a cleanup.
- **No multi-DE.** Hyprland is the desktop.