Nomarchy/docs/ROADMAP.md

Nomarchy Roadmap

This is the mid-term plan for Nomarchy. It exists so future sessions — human or agent — can pick up work without re-deriving context. Items move from Now → Next → Later as priorities shift, and from any column into Shipped at the bottom when done. There are no dates: ship-when-ready.

If you're new here, also read docs/STRUCTURE.md and docs/OPTIONS.md. Existing-NixOS users should also read docs/MIGRATION.md.

1. Vision & guardrails

Nomarchy is a NixOS-based distribution that gives you a polished Hyprland desktop (Hyprland + waybar + walker + a curated theming engine) on a strictly declarative, flake-based foundation. Goal: power-user polish without giving up reproducibility.

Guardrails (apply when adding anything):

• Declarative-first. No imperative state in core/. Anything mutable lives in ~/.config/nomarchy/state.json or in NixOS options.
• Downstream-flake friendly. Every behavior toggle is a nomarchy.* option documented in docs/OPTIONS.md. Adding a feature without a corresponding option is a bug.
• Opt-in by default. New features default off (or default to the existing behavior). The installer can flip defaults for the user, but the option must read sensibly when set by hand.
• Reuse before invent. Before adding a script, grep core/system/scripts/, features/scripts/utils/, and themes/engine/scripts/ — there are ~155 of them, and many of the things you want already exist.

2. Now / Next / Later board

Now (ready to pick up)

• (Empty for now)

Next (bigger lifts that build on Now)

• Accessibility — home-side companion. Hyprland-side bits the system preset can't reach: slower input.repeat_rate / repeat_delay defaults, SUPER+ALT+S keybinding to launch Orca, and a high-contrast palette under themes/palettes/. Gated on a new nomarchy.accessibility.enable mirror of the system option.
• 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.
• Plymouth theme variants per palette. Currently one Plymouth theme; could template per-palette so the boot splash matches the active theme.

Later (speculative or research-shaped)

• Declarative-state migration. Move the bits of state.json that don't actually need runtime mutability (theme, font, isLightMode) into NixOS / home-manager options, leaving only genuinely runtime-only state behind. Reduces the "two sources of truth" surface.
• Rolling vs pinned channel choice in the installer. Today the generated flake pins nomarchy to a rev. Offer a "rolling" option that follows main and a nomarchy-rollback helper for stuck rebuilds.
• Theme creation wizard. A nomarchy-theme-new script that scaffolds a new palette from a base16 hex set (or by sampling a wallpaper), runs nomarchy-themes-prebuild, and opens a PR template.
• CI matrix on Forgejo Actions. On every push: nix flake check, build nomarchy-installer, nomarchy-live, default. On tag: publish ISOs as release artefacts.
• Golden-image VM tests per palette. A nixosTest per palette that boots the default config, takes a screenshot, and diffs against a golden image. Catches Stylix regressions before they hit users.
• Forgejo release pipeline. vYY.MM.x tags matching the upstream NixOS channel; the pipeline pushes the three ISOs and an updated flake.lock snapshot.
• Optional nomarchy-installer-vm rebuilt as a real flake app (not a one-off shell script) so users can install Nomarchy into a libvirt VM declaratively.
• Surface support module via the relevant nixos-hardware profile + Surface kernel patches behind a nomarchy.hardware.isSurface toggle.

3. Pillar: Script & menu audit

Nomarchy ships ~155 nomarchy-* scripts across three directories, plus a 379-line nomarchy-menu with 23 submenu functions. Some are first-class Nomarchy work; some are direct Omarchy ports that haven't been adapted; some are dangling references the menu calls but no script implements (e.g. nomarchy-backup, nomarchy-debug, nomarchy-pkg, nomarchy-pkg-aur-add, nomarchy-plymouth, nomarchy-refresh-hyprland, nomarchy-reinstall, nomarchy-rollback, nomarchy-screenrecord-filename, nomarchy-theme, nomarchy-update-firmware, nomarchy-upload-log, nomarchy-version, nomarchy-wallpaper, nomarchy-skill, nomarchy-luks).

This pillar fixes that. It runs as two phases.

Phase A — Inventory & triage

Lands as a single PR. Output is docs/SCRIPTS.md populated with rows for every script and every menu item.

1. Run a generator (one-shot helper, doesn't have to be checked in) that produces three lists:
   • All nomarchy-* scripts under core/system/scripts/, features/scripts/utils/, themes/engine/scripts/.
   • All nomarchy-* callers (grep core/, features/, themes/, installer/, bin/).
   • The set difference (orphaned callers ↔ unreferenced scripts).
2. Walk features/scripts/utils/nomarchy-menu and list every menu entry with its target script.
3. Tag each row with a status:
   • kept — works on Nomarchy, no change needed.
   • port-from-omarchy — exists upstream, needs adapting (drop pacman/yay/AUR, repath to NixOS, talk to nomarchy.system.* options).
   • delete-dead — neither used nor needed; remove and update callers.
   • stub-with-notify — temporarily replace with a notify-send "Not yet implemented in Nomarchy" so the menu stops looking broken until the work is scheduled.
   • unknown — needs a deeper look before tagging.
4. The completed table lives at docs/SCRIPTS.md. The roadmap links to it; this section just sets the methodology.

Phase B — Adapt or remove

Lands as PR batches of ~10 scripts each, branch named wave/audit-<batch>. Per script:

• For port-from-omarchy: rewrite the script for Nomarchy paths (/etc/nixos, nixos-rebuild, home-manager, no Arch idioms), wire it into nomarchy.system.* where applicable, and update every caller (menu, waybar, keybindings).
• For delete-dead: git rm the script and fix every caller — a find + sed pass against nomarchy-menu, every *.conf, and every nix file.
• For stub-with-notify: write the one-liner stub in place. The roadmap row stays open until the real implementation lands.

Each PR description should reference the row(s) in docs/SCRIPTS.md it closes, and reviewers spot-check that no caller still points at a stale name.

4. Pillar: Installer

• Software-profile multi-select (Now).
• Richer disk metadata (Shipped).
• Form-factor → laptop preset (Now, depends on Pillar 5).
• disko-golden.nix variants for software-RAID and BTRFS-pool-as-root (Shipped).
• Pre-flight resume polish (Next).
• "What's installed?" summary screen on boot of a freshly-installed system, sourced from state.json + nomarchy-system-scripts introspection.
• Optional non-LUKS branch in the installer for users who explicitly opt out of FDE.

5. Pillar: Power, hardware, presets

• Laptop preset (Next): TLP, upower, brightness, lid, hypridle tuning.
• Desktop preset (Next): performance governor, no laptop UI (already filtered), ZFS hooks.
• Accessibility preset (Next).
• Gaming preset (Next).
• Vendor matchers in installer/hardware-db.sh: Steam Deck, Surface, ROG Ally, Snapdragon X laptops.
• Surface support behind nomarchy.hardware.isSurface (Later).
• Auto-detect dGPU presence and offer programs.envycontrol-style switching for the hybrid case (already gated behind nomarchy.system.features.hybridGPU, but the wiring is minimal).

6. Pillar: Onboarding & docs

• nomarchy-welcome first-run wizard (Next).
• docs/KEYBINDINGS.md auto-generator (Shipped).
• docs/TROUBLESHOOTING.md (Next).
• docs/index.md (or just enrich README.md) so OPTIONS.md, STRUCTURE.md, MIGRATION.md, ROADMAP.md, SCRIPTS.md, and creating-themes.md are all one click from the front page.
• nomarchy-manual — orphaned reference today; either implement as a curated xdg-open to the docs index, or delete.

7. Pillar: Test, CI, release

• Forgejo Actions workflow:
  • on every push to main: nix flake check (≈ what we run by hand today).
  • on every PR: also build all three ISOs (cache hit on most of them).
  • on tag vYY.MM.x: publish ISOs as release artefacts.
• Versioning scheme: vYY.MM.x matching the upstream NixOS channel (e.g. v25.11.3).
• nixosTest per palette: boots default in a VM, screenshots the SDDM splash and the Hyprland desktop, diffs vs golden. Failure surfaces as CI red.
• A small bin/utils/nomarchy-bench-iso-build that records ISO build time + size into a per-commit JSON so we notice regressions.

9. Process notes

• Branch naming: wave/<pillar>-<short-slug>. Examples: wave/audit-pkg-scripts, wave/installer-disk-metadata, wave/laptop-preset.
• One PR per audit batch. Reference rows in docs/SCRIPTS.md. Smaller PRs review faster.
• Living roadmap. When an item ships, move it to the Shipped section at the bottom of this file rather than deleting it. Future-us gets a free changelog.
• Plan files live separately. Detailed implementation plans (the per-feature design docs Claude writes in plan mode) belong under ~/.claude/plans/ per session, not in the repo. The roadmap is the durable reference; plan files are working notes.
• Don't widen scope mid-PR. If the audit reveals a missing feature, file a new roadmap row, don't graft it onto the current PR.

Shipped

(Move items here when they land — keep them brief, link the commit/PR.)

• 2026-05-18 — Pillar 3 Phase B: webapp/tui/voxtype install-remove pair triage. Deleted two dead webapp URI handlers (nomarchy-webapp-handler-hey, nomarchy-webapp-handler-zoom) — no .desktop MimeType registration anywhere routed mailto:/zoom: URIs to them, so the handlers could never fire. Surfaced six useful CLI tools in SKILL.md "Common Tasks" so they're discoverable by AI assistants and tagged kept by the audit: nomarchy-webapp-{remove,remove-all}, nomarchy-tui-{remove,remove-all}, nomarchy-voxtype-{install,remove}. Script count 166 → 164; unused? 21 → 13.
• 2026-05-18 — Pillar 3 Phase B: dead-code sweep (NixOS-irrelevant Omarchy ports). Deleted five scripts that duplicated NixOS-native facilities or referenced infrastructure Nomarchy doesn't ship: nomarchy-rollback (boot-menu generations + nixos-rebuild rollback already cover this), nomarchy-snapshot (used snapper; impermanence and BTRFS subvolumes are the Nomarchy answer), nomarchy-migrate-state (one-shot pre-unification migration, no current callers), nomarchy-config-direct-boot (added an EFI entry for a UKI we never build), and nomarchy-npx-install (Arch idiom — nix-shell -p nodejs is the NixOS path). Kept nomarchy-build-iso and nomarchy-build-live-iso and surfaced them in README §2 so the audit tags them kept. Script count 171 → 166.
• 2026-05-18 — Pillar 3 Phase B: missing-references triage. (1) Wrote themes/engine/scripts/nomarchy-theme-next so SKILL.md's documented "cycle to next theme" command resolves; (2) scrubbed three stale nomarchy-dev-* references from core/home/config/nomarchy-skill/SKILL.md; (3) added a line-context filter to both nomarchy-docs-scripts generators that drops nomarchy-* tokens appearing in Nix pname/derivation idents, /tmp/ & /etc/sudoers.d/ paths, nixosConfigurations.* / packages.* flake outputs, mktemp -t prefixes, systemd unit vars, ./result/bin/run- binaries, and docker container references; (4) added a small token-level denylist for five residual non-script identifiers (nomarchy-plymouth, nomarchy-sddm-theme, nomarchy-live, nomarchy-rev, nomarchy-windows) that survive line filtering. docs/SCRIPTS.md "Missing references" section is now empty (was 15).
• 2026-05-04 — Pillar 8: Distro Branding. (1) Scrubbed remaining "Omarchy" and "Spirit of Omarchy" references from README, scripts, and welcome wizard; (2) Updated nomarchy-welcome banner and nomarchy-version codename ("Sovereign"); (3) Verified existing core/system/branding.nix handles OS-release and bootloader labels; (4) Confirmed SDDM and Plymouth metadata are already Nomarchy-branded.
• 2026-05-04 — Thorough Out-of-the-Box QA Audit. (1) Restored automatic wallpaper switching by removing image filters from deployed themes; (2) Fixed broken "Style" menu entries by creating missing about.txt and screensaver.txt branding files; (3) Cleaned up conflicting keybindings by removing deprecated tiling.conf and updating the doc generator; (4) Removed legacy Nord theme hack from nomarchy-theme-set; (5) Fixed JSON parse error in summer-day waybar theme.
• 2026-05-03 — Fixed multi-disk LUKS/BTRFS boot hang. (1) Moved temporary LUKS keyfile to /tmp/ so Disko correctly omits it from the runtime configuration; (2) Injected x-systemd.requires and x-systemd.device-timeout=0 into BTRFS mount options to ensure all LUKS drives are decrypted before mounting.
• 2026-05-03 — Fixed CLI wrappers and removed obsolete code. (1) Updated nomarchy-font, nomarchy-theme, and nomarchy-wallpaper CLI wrappers to use modern Walker menus; (2) Removed the obsolete and broken themes/engine/switcher.nix and its associated Nix-inlined scripts; (3) Cleaned up remaining $NOMARCHY_PATH references from the Omarchy era.
• 2026-05-03 — Fixed /etc/nixos ownership after installation. Added a chown -R $USERNAME:users /etc/nixos step via nixos-enter at the end of installer/install.sh so the main user owns their configuration and can run home-manager commands without sudo.
• 2026-05-01 — Installer & Script Audit Polish. (1) Fixed a critical bash dynamic scoping bug in installer/install.sh where rc=0 assignments inside functions (Impermanence, Form Factor) were clobbering the main loop's return code, causing the installer to abort when "No" was selected; (2) Polished hosts/nomarchy-live.nix with auto-login for the nixos user and passwordless sudo for the wheel group; (3) Repurposed nomarchy-toggle-suspend to execute systemctl suspend directly and updated nomarchy-menu to reflect this; (4) Updated nomarchy-launch-wifi to use nmtui in Alacritty; (5) Regenerated docs/SCRIPTS.md to reflect the updated script mappings.
• 2026-04-30 — set -e sweep across nomarchy-* scripts. Added set -e to 142 of 169 bash scripts that lacked it (27 already had it). Halts a class of "command failed silently in the middle of a chain, system left in half-applied state" bugs that produced repeat-fix commits. One deliberate exception: nomarchy-menu runs without set -e because it's an interactive UX loop where action failures should re-display the menu rather than abort the script. Pre-commit hook now enforces bash -n + shellcheck --severity=error so future scripts can't regress this.
• 2026-04-30 — Installer disk-phase reliability. Hardened installer/install.sh and consolidated the disko configs: (1) select_disk now hides the live-ISO boot device(s) so the installer can't format its own boot media (NOMARCHY_INSTALL_ALLOW_ISO_TARGET=1 to override); (2) added a 10 GiB minimum-capacity preflight; (3) prewipe_target_drive enumerates every active dm-crypt mapping backed by the target drive and closes them, drops the silent || true from wipefs/sgdisk/dd, bounds udevadm settle to 30s, and refuses to continue if anything is still mounted; (4) wrapped the disko call in run_disko_with_retry with last-30-lines + Retry / View full log / Abort dialog on failure; (5) replaced the sed-templated disko-golden.nix + disko-btrfs-multi.nix pair with a single disko-config.nix Nix function called via --argstr mainDrive … --arg extraDrives '[…]' — eliminates a class of escaping bugs (cf. 3aadc36); (6) added an EXIT trap so the tmpfs LUKS key file is removed even on early abort.
• 2026-04-30 — Gaming home-side companion. New nomarchy.gaming.enable option (mirror of nomarchy.system.gaming.enable) and core/home/gaming.nix module that injects a Hyprland windowrulev2 = fullscreen, class:^(steam_app_).*$ so Steam-launched games grab the whole screen. Closes the "Gaming — Hyprland window rule" Next-column row.
• 2026-04-26 — Default to highest resolution (highres) for monitors. Updated features/desktop/hyprland/config/monitors.conf and forced it in the live ISO (nomarchy-live) to resolve issues where some hardware would default to a low resolution (1024x768).
• 2026-04-26 — First-run welcome wizard (nomarchy-welcome). Extended from a one-shot greeter into a guided picker for theme, font, and panel position. Added Step 4 to generate a starter home.nix if missing. State is now persisted in state.json via .welcome_done. Added nomarchy.panelPosition option to Waybar.
• 2026-04-26 — Multi-disk BTRFS support in the installer. Added installer/disko-btrfs-multi.nix template and updated installer/install.sh to allow selecting multiple drives via gum choose --no-limit. Implements BTRFS "single" data + RAID1 metadata across multiple LUKS-encrypted drives.
• 2026-04-26 — Distro Branding Phase 2. Updated bootloader entries to use "Nomarchy" as the label. Set ISO volume IDs to NOMARCHY_INSTALLER and NOMARCHY_LIVE. Fixed branding in Plymouth theme metadata and SDDM metadata.
• 2026-04-26 — Distro Branding Phase 1. Renamed installerIso to nomarchy-installer and installerIsoGraphical to nomarchy-live. Updated metadata and host configurations. Scrubbed "Omarchy" from Plymouth and installer messages.
• 2026-04-26 — Fix hardware-db.sh missing in nomarchy-installer.nix. Resolved boot error where install.sh failed to source the hardware database on the TTY installer ISO.
• 2026-04-26 — Installer review-then-edit flow (installer/install.sh). Review screen now offers Continue / Edit a field / Abort. Edit opens a multi-select of saved fields; chosen fields clear and the next loop iteration re-prompts only those. Benefits both fresh installs (typo fixes without abort+restart) and --resume (lands on review immediately, since the loaded vars short-circuit each prompt). LUKS passphrase is held in memory across loop iterations so re-edits don't re-ask for it.
• 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.
• 2026-04-26 — Laptop preset module (core/system/laptop.nix). New nomarchy.system.laptop.{enable,thermald} options; enable defaults to formFactor == "laptop" so the installer's existing formFactor write auto-flips it on. Wires TLP (governors + 75/80 charge thresholds), force-disables power-profiles-daemon, enables upower and thermald (x86_64), adds the brightnessctl udev rule for backlight without root, and sets a logind lid-switch policy that defers to hibernation.enable. Closes both the Now item and the largest Next item.
• 2026-04-25 — Software-profile multi-select in the installer. Users can now pick Dev, Gaming, Office, Media, and CLI Utils profiles during install; logic emits corresponding home.packages and system toggles into the generated config.
• 2026-04-25 — Pillar 3 Phase B: script & menu audit. Ported/implemented/stubbed ~40 scripts including nomarchy-version, nomarchy-debug, nomarchy-reinstall, nomarchy-rollback, nomarchy-update-firmware, nomarchy-pkg-*, and nomarchy-theme-* wrappers. Moved desktop scripts to packaged utility directory.
• 2026-04-25 — Docker & fwupd support. Added nomarchy.system.virtualization.docker.enable and nomarchy.hardware.fwupd options. Wires system services and adds docker-compose and fwupdmgr to PATH.
• 2026-04-25 — Installer VM testing. Added installerVm to flake nixosConfigurations, packages, and apps. nomarchy-test-installer now uses nix run .#installerVm.
• 2026-04-25 — docs/KEYBINDINGS.md auto-generator. New repo-tooling script bin/utils/nomarchy-docs-keybindings parses every bindd = / bindeld = line into a Markdown doc; README's keybinding table slimmed to highlights + link.
• 2026-04-25 — Installer disk picker shows NAME / SIZE / TYPE / VENDOR / MODEL / SERIAL columns instead of bare lsblk. Type derived from ROTA + TRAN (NVMe / USB / SSD / HDD). Filters loop, ram, zram, sr.
• 2026-04-25 — Pillar 3 Phase A: script & menu audit. New bin/utils/nomarchy-docs-scripts generator produces docs/SCRIPTS.md with 136 scripts and the menu walk pre-tagged via heuristics (kept / unused? / missing). Phase B (per-batch porting / removal) opens.
• 2026-04-25 — Installer prompts for keyboard layout + locale, applies live; new nomarchy.{system,}.formFactor option; waybar drops battery widget on desktop; nm-applet visibility fix in default theme; live-ISO baseline keymap/locale (a7e7fa9).
• 2026-04-25 — docs/OPTIONS.md reference; docs/MIGRATION.md linked from README.md (3cb012b, 6ef28f0).