feat(scripts): extend nomarchy-welcome into a guided wizard

- Added nomarchy.panelPosition option and state persistence.
- Updated Waybar to respect the panelPosition setting.
- Refactored nomarchy-welcome to use state.json instead of a flag file.
- Added prompts for theme, font, panel position, and starter home.nix generation.
- Updated documentation and roadmap.

core/home/options.nix

@@ -61,6 +61,11 @@
       default = "";
       description = "System wallpaper path.";
     };
+    panelPosition = lib.mkOption {
+      type = lib.types.enum [ "top" "bottom" ];
+      default = "top";
+      description = "Waybar panel position.";
+    };
     hyprland = {
       gaps_in = lib.mkOption {
         type = lib.types.int;

core/home/state.nix

@@ -21,6 +21,7 @@ in
       nightlightTemperature = togglesState.nightlightTemperature or 4000;
       theme = togglesState.theme or "summer-night";
       wallpaper = togglesState.wallpaper or "";
+      panelPosition = togglesState.panelPosition or "top";
       hyprland = {
         gaps_in = togglesState.hyprland.gaps_in or 5;
         gaps_out = togglesState.hyprland.gaps_out or 10;

docs/OPTIONS.md

@@ -147,6 +147,10 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 `str`, default `"summer-night"`. Active theme name. Available themes are the directories under `themes/palettes/`.
 
+### `nomarchy.panelPosition`
+
+`enum ["top", "bottom"]`, default `"top"`. Waybar panel position.
+
 ### `nomarchy.formFactor`
 
 `enum [ "laptop" "desktop" ]`, default `"laptop"`. Mirror of `nomarchy.system.formFactor`. Filters laptop-only widgets out of waybar (battery) when set to `"desktop"`. The installer writes both system and home values together.

docs/ROADMAP.md

@@ -26,7 +26,6 @@ Guardrails (apply when adding anything):
 - **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 — Hyprland window rule.** Companion to the gaming preset: a Hyprland `windowrulev2 = fullscreen, class:^(steam_app_).*$` (or similar) so games launched from Steam grab the whole screen. Lives in `core/home/config/nomarchy/default/hypr/` and gates on a new `nomarchy.gaming.enable` mirror.
 - **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.
 
 ### Later (speculative or research-shaped)
@@ -138,6 +137,7 @@ Nomarchy is moving away from being a "flavor" of Omarchy to its own distinct ide
 
 (Move items here when they land — keep them brief, link the commit/PR.)
 
+- _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.

docs/SCRIPTS.md

@@ -135,8 +135,8 @@ Phase B (per-batch PRs) refines those into `port-from-omarchy`,
 | `nomarchy-show-logo` | `themes/engine/scripts` | features/scripts/utils/nomarchy-launch-floating-terminal-with-presentation | `kept` |  |
 | `nomarchy-skill` | `features/scripts/utils` | core/home/configs.nix | `kept` |  |
 | `nomarchy-snapshot` | `features/scripts/utils` | — | `unused?` |  |
-| `nomarchy-state` | `features/scripts/utils` | core/system/scripts/nomarchy-system-reboot,core/system/scripts/nomarchy-system-shutdown, +1 more | `kept` |  |
+| `nomarchy-state` | `features/scripts/utils` | core/system/scripts/nomarchy-system-reboot,core/system/scripts/nomarchy-system-shutdown, +2 more | `kept` |  |
-| `nomarchy-state-write` | `features/scripts/utils` | — | `unused?` |  |
+| `nomarchy-state-write` | `features/scripts/utils` | features/scripts/utils/nomarchy-welcome | `kept` |  |
 | `nomarchy-sudo-keepalive` | `core/system/scripts` | — | `unused?` |  |
 | `nomarchy-sudo-passwordless-toggle` | `core/system/scripts` | — | `unused?` |  |
 | `nomarchy-sudo-reset` | `core/system/scripts` | — | `unused?` |  |
@@ -213,7 +213,7 @@ Tokens grepped from `core/`, `features/`, `themes/`, `installer/`, `hosts/`, `bi
 | `nomarchy-installer` | features/scripts/utils/nomarchy-build-iso,README.md | `missing` |
 | `nomarchy-launch` | core/home/config/nomarchy/default/hypr/bindings/clipboard.conf,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +24 more | `missing` |
 | `nomarchy-live` | features/scripts/utils/nomarchy-build-live-iso,features/scripts/utils/nomarchy-on-boot, +1 more | `missing` |
-| `nomarchy-luks` | installer/disko-golden.nix,installer/install.sh | `missing` |
+| `nomarchy-luks` | installer/disko-btrfs-multi.nix,installer/disko-golden.nix, +1 more | `missing` |
 | `nomarchy-menu-rows` | bin/utils/nomarchy-docs-scripts,features/scripts/utils/nomarchy-docs-scripts | `missing` |
 | `nomarchy-nopasswd` | core/system/scripts/nomarchy-sudo-passwordless-toggle | `missing` |
 | `nomarchy-nopasswd-expire` | core/system/scripts/nomarchy-sudo-passwordless-toggle | `missing` |

features/desktop/waybar/default.nix

@@ -28,6 +28,7 @@ let
     else builtins.filter (m: !(builtins.elem m laptopOnlyModules)) mods;
 
   settings = rawSettings // {
+    position = config.nomarchy.panelPosition;
     modules-left   = filterModules (rawSettings.modules-left   or []);
     modules-center = filterModules (rawSettings.modules-center or []);
     modules-right  = filterModules (rawSettings.modules-right  or []);

features/scripts/utils/nomarchy-welcome

@@ -1,9 +1,13 @@
 #!/usr/bin/env bash
 
-FLAG_FILE="$HOME/.config/nomarchy/.first-run-done"
+STATE_FILE="$HOME/.config/nomarchy/state.json"
 
-if [ -f "$FLAG_FILE" ]; then
+# Check if welcome wizard has already been completed
-    exit 0
+if [ -f "$STATE_FILE" ]; then
+    DONE=$(jq -r '.welcome_done' "$STATE_FILE" 2>/dev/null)
+    if [ "$DONE" == "true" ]; then
+        exit 0
+    fi
 fi
 
 # Ensure we have a terminal for the wizard
@@ -29,8 +33,44 @@ nomarchy-theme-set "$(nomarchy-theme-list | gum filter --placeholder 'Select a t
 echo "Step 2: Choose your preferred font"
 nomarchy-font-set "$(nomarchy-font-list | gum filter --placeholder 'Select a font...')"
 
-# 3. Setup Local Repo (Crucial for nomarchy-env-update to work)
+# 3. Select panel position
+echo "Step 3: Choose your preferred panel position"
+POSITION=$(gum choose "top" "bottom")
+nomarchy-state-write panelPosition "$POSITION"
+
+# 4. Starter home.nix
 echo ""
+echo "Step 4: Starter home.nix"
+HOME_NIX="$HOME/.config/home-manager/home.nix"
+if [ ! -f "$HOME_NIX" ]; then
+    echo "It looks like you don't have a ~/.config/home-manager/home.nix file yet."
+    echo "Nomarchy uses this file to manage your user-level packages and settings."
+    if gum confirm "Would you like to generate a starter home.nix?"; then
+        mkdir -p "$(dirname "$HOME_NIX")"
+        cat <<EOF > "$HOME_NIX"
+{ pkgs, ... }:
+{
+  # Nomarchy starter home.nix
+  # Add your user packages here.
+  home.packages = with pkgs; [
+    btop
+    fastfetch
+    chromium
+    # Add more packages here
+  ];
+
+  # home.stateVersion = "25.11"; # Consult docs/MIGRATION.md if you change this
+}
+EOF
+        echo "Starter home.nix generated at $HOME_NIX"
+    fi
+else
+    echo "Detected existing home.nix at $HOME_NIX. Skipping generation."
+fi
+
+# 5. Setup Local Repo (Crucial for nomarchy-env-update to work)
+echo ""
+echo "Step 5: Git Repository Check"
 echo "Nomarchy relies on a local git repository for declarative updates."
 if [ ! -d "/etc/nixos/.git" ]; then
     echo "Warning: /etc/nixos is not a git repository. Declarative updates might fail."
@@ -41,9 +81,11 @@ if [ ! -d "/etc/nixos/.git" ]; then
     fi
 fi
 
-# 4. Success
+# 6. Success
-mkdir -p "$(dirname "$FLAG_FILE")"
+nomarchy-state-write welcome_done true --type bool
-touch "$FLAG_FILE"
+
+# Remove legacy flag file if it exists
+rm -f "$HOME/.config/nomarchy/.first-run-done"
 
 gum style --foreground 82 "Setup complete! Enjoy your Nomarchy experience."
 sleep 3

lib/state-schema.nix

@@ -9,6 +9,7 @@
     theme = "nord";
     wallpaper = "";
     font = "JetBrainsMono Nerd Font";
+    panelPosition = "top";
     nightlightTemperature = 4000;
 
     # Feature toggles