diff --git a/README.md b/README.md index cbfeeff..7905023 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ Add user-level packages, aliases, and dotfiles here. 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). For where the project is heading next, see the [Roadmap](docs/ROADMAP.md). +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: diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 62d69c0..086acd4 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -216,6 +216,9 @@ Impermanence is **off** unless you set `nomarchy.system.impermanence.enable = tr and it requires a BTRFS layout with a `root-blank` snapshot. Don't enable it on an existing install — the live ISO is the right path for that. +If your first rebuild errors out, the five most common failures and their fixes +live in [Troubleshooting](TROUBLESHOOTING.md). + --- ## Fallback: clean install via the live ISO diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 55c966c..f273a71 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -28,7 +28,6 @@ Guardrails (apply when adding anything): - **Gaming — declarative flathub remote.** `services.flatpak.enable` doesn't ship a declarative remote API in nixpkgs. Either add the `flatpak-managed-install` overlay, write a one-shot systemd unit that runs `flatpak remote-add --if-not-exists flathub …`, or surface the manual step in `nomarchy-welcome`. - **First-run welcome wizard.** Extend `nomarchy-welcome` from a one-shot greeter into a guided picker: theme, panel position, monospace font, "what's a sane home.nix to start with?". Runs once, persists "done" in `state.json`. - **Plymouth theme variants per palette.** Currently one Plymouth theme; could template per-palette so the boot splash matches the active theme. -- **`docs/TROUBLESHOOTING.md`.** The five most common rebuild errors (`option ... already declared`, `attribute ... missing`, Stylix target conflicts, home-manager backupFileExtension churn, impermanence path missing) with copy-paste fixes. - **Installer pre-flight resume polish.** If the user Ctrl-Cs mid-install and runs `--resume`, re-show the review screen before re-prompting for any unsaved fields. ### Later (speculative or research-shaped) @@ -125,6 +124,7 @@ Each PR description should reference the row(s) in `docs/SCRIPTS.md` it closes, (Move items here when they land — keep them brief, link the commit/PR.) +- _2026-04-26_ — `docs/TROUBLESHOOTING.md`. The five most common rebuild errors (option-already-declared, attribute-missing, Stylix target conflict, home-manager `.hm-bak` churn, impermanence path missing) with copy-paste fixes. Linked from `README.md` and `docs/MIGRATION.md`. - _2026-04-26_ — Gaming preset module (`core/system/gaming.nix`). Opt-in `nomarchy.system.gaming.enable` (default false). Wires `programs.steam` (with `remotePlay`/`localNetworkGameTransfers` firewall holes via `mkDefault`), `programs.gamemode`, and `services.flatpak`. Flathub remote and Hyprland window-rule split into separate Next-column rows. - _2026-04-26_ — Accessibility preset module (`core/system/accessibility.nix`). New `nomarchy.system.accessibility.{enable,cursorSize}` options (opt-in, default off — accessibility isn't a hardware-derived signal). Enables `services.gnome.at-spi2-core`, installs Orca, and sets `XCURSOR_SIZE=32` (configurable). Hyprland-side companion (key-repeat slowdown, Orca keybinding, high-contrast palette) split into a new Next-column row. - _2026-04-26_ — Desktop preset module (`core/system/desktop.nix`). New `nomarchy.system.desktop.enable` option; defaults to `formFactor == "desktop"` (mirror of the laptop preset's auto-enable). Pins `powerManagement.cpuFreqGovernor` to `"performance"` and enables `services.zfs.{autoScrub,trim}` so a future ZFS pool gets sensible maintenance for free. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..460accf --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,121 @@ +# Troubleshooting + +The five rebuild errors a Nomarchy user is most likely to hit, with copy-paste fixes. If your error isn't here, the [Options Reference](OPTIONS.md) and [Migration Guide](MIGRATION.md) cover most other surfaces. + +--- + +## 1. `error: The option 'X' is already declared in multiple modules` + +**Looks like:** + +``` +error: The option `services.foo.enable' is already declared in multiple modules: + - /nix/store/…-source/modules/foo.nix + - /nix/store/…-source/core/system/foo.nix +``` + +**Cause:** Two modules — usually one of yours and one of Nomarchy's — both `mkOption` the same path. Nix can't merge two declarations of the *same option*; it can only merge two *values* for one option. + +**Fix:** Find the duplicate. If it's yours and Nomarchy's, delete yours; Nomarchy already declares it. If it's two of yours, delete one. To grep: + +```bash +grep -rn "options\..*foo\.enable" /etc/nixos +``` + +--- + +## 2. `error: attribute 'X' missing` + +**Looks like:** + +``` +error: attribute 'nomarchy' missing + at /etc/nixos/system.nix:7:5: + 7| nomarchy.system.formFactor = "laptop"; +``` + +**Cause:** You're setting `nomarchy.*` options but didn't import the Nomarchy modules. The flake's `nixosModules.system` declares the option namespace; without the import, the option doesn't exist. + +**Fix:** In your `/etc/nixos/flake.nix`, make sure both modules are in the system's `modules = [ … ]` list: + +```nix +modules = [ + nomarchy.nixosModules.system + ./system.nix + ./hardware-selection.nix +]; +``` + +The home side is the same shape — `nomarchy.nixosModules.home` plus your `./home.nix`. See [MIGRATION.md](MIGRATION.md) for the full skeleton. + +--- + +## 3. Stylix target conflict + +**Looks like:** + +``` +error: The option `stylix.targets.gtk.enable' has conflicting definition values: + - In `/nix/store/…/stylix.nix': true + - In `/etc/nixos/home.nix': false +Use `lib.mkForce' or `lib.mkDefault' to resolve. +``` + +**Cause:** Stylix's per-target options are `bool`, not `enum`, so two equally-priority `true`/`false` values from two modules collide. Nomarchy's theming engine sets most targets to `true` via `mkDefault`, so the conflict almost always means *you* set one without `mkDefault`. + +**Fix:** Wrap your override in `lib.mkForce`: + +```nix +stylix.targets.gtk.enable = lib.mkForce false; +``` + +If you want the default-on behavior back, just delete your line — Nomarchy's default fires automatically. + +--- + +## 4. home-manager `backupFileExtension` churn + +**Looks like:** every rebuild leaves another `~/.config/foo/bar.conf.hm-bak` next to the file home-manager just wrote, until your `~/.config` is half backups. + +**Cause:** home-manager refuses to overwrite files it didn't itself write; it backs them up first. Nomarchy's flake sets `backupFileExtension = "hm-bak"` (see `flake.nix:161,210`) so the first rebuild after a fresh ISO install doesn't fail — but every subsequent rebuild then re-backs-up the same files because the previous backup is still there. + +**Fix:** After the first successful rebuild, delete the backups: + +```bash +find ~/.config -name '*.hm-bak' -print -delete +``` + +If churn continues, you have a config under `~/.config//` that home-manager wants to manage but you've also touched by hand. Either let home-manager own it (don't edit by hand; use `nomarchy.*` options or `~/.config/nomarchy/overrides/`) or delete the home-manager declaration if you want the file to remain user-mutable. + +--- + +## 5. impermanence path missing after a wipe + +**Looks like:** after enabling `nomarchy.system.impermanence.enable = true;` and rebooting, an app forgets state — Bluetooth pairings vanish, NetworkManager forgets Wi-Fi, GPG keys are gone — or the rebuild itself errors with: + +``` +error: The path '/persist' does not exist +``` + +**Cause:** Impermanence requires (a) a `/persist` mountpoint that survives the boot wipe, and (b) every directory you want to keep must be in the persistence list. Nomarchy persists the basics in `core/system/impermanence.nix:46-72` (NetworkManager, Bluetooth, fprint, SSH host keys, the user's `.ssh` / `.gnupg` / Documents / Downloads / Pictures / Videos / Projects). Anything else you care about — Steam library, Flatpak data, custom dotfiles — must be added. + +**Fix:** Make sure `/persist` is mounted (check `mount | grep persist`). Then add the missing path in your `system.nix`: + +```nix +environment.persistence."/persist".users.nomarchy.directories = [ + ".local/share/Steam" + ".var/app" # flatpak data + ".local/share/keyrings" # already in Nomarchy defaults — example only +]; +``` + +Per-app data lives in `~/.local/share/` or `~/.var/app/` (flatpak); check the app's docs. After adding, rebuild and reboot — the path is created on the next mount of `/persist`. + +--- + +## Where to look next + +- **Option reference:** [docs/OPTIONS.md](OPTIONS.md) — every `nomarchy.*` setting. +- **Existing-NixOS install:** [docs/MIGRATION.md](MIGRATION.md) — how to layer Nomarchy onto a working NixOS without reformatting. +- **Repo layout:** [docs/STRUCTURE.md](STRUCTURE.md) — where each module lives. +- **Roadmap:** [docs/ROADMAP.md](ROADMAP.md) — what's planned and what's shipped.