feat(scripts): Add --help flags to all flake apps

Add consistent --help/-h argument handling to update-doomemacs.sh,
rotate-wallpaper.sh, and upgrade.sh scripts. Each script now displays
usage information and a description of what it does.

update-claude-code already had --help support.

.goosehints

@@ -9,7 +9,7 @@ Directory Structure:
 ----------------------
 • packages/      - Custom Nix packages leveraged across various configurations.
 • roles/         - Role-based configurations (e.g., kodi, bluetooth) each with its own module (default.nix) for inclusion in machine setups.
-• machines/      - Machine-specific configurations (e.g., nix-book, zix790prors, boxy) including configuration.nix and hardware-configuration.nix tailored for each hardware.
+• machines/      - Machine-specific configurations (e.g., nix-book, z790prors, boxy, wixos) including configuration.nix and hardware-configuration.nix tailored for each hardware.
 • home/          - Home-manager configurations for personal environments and application settings (e.g., home-nix-book.nix, home-z790prors.nix).
 
 Design Principles:

AGENTS.md

@@ -14,7 +14,7 @@ This repository uses `beads` for issue tracking and management. Run `bd quicksta
 
 ### Flake Structure
 - **flake.nix**: Main entry point defining inputs (nixpkgs, home-manager, plasma-manager, etc.) and outputs for multiple NixOS configurations
-- **Machines**: `nix-book`, `boxy`, `zix790prors`, `live-usb`, `johno-macbookpro` (Darwin/macOS)
+- **Machines**: `nix-book`, `boxy`, `wixos` (WSL configuration), `zix790prors`, `live-usb`, `johno-macbookpro` (Darwin/macOS)
 - **Home configurations**: Standalone home-manager configuration for user `johno`
 
 ### Directory Structure
@@ -78,6 +78,7 @@ The repository also uses a modular home-manager role system for user-space confi
 - **nix-book**: Compact laptop → excludes office/media roles due to SSD space constraints
 - **boxy**: Living room media center → optimized for media consumption, excludes sync/office (shared machine)
 - **zix790prors**: All-purpose workstation → full desktop experience with all roles enabled
+- **wixos**: WSL2 development → full desktop experience, inherits from zix790prors Windows host
 - **live-usb**: Temporary environment → only base + desktop roles, no persistent services
 - **johno-macbookpro**: macOS work laptop → Darwin-specific configuration with development tools
 
@@ -110,6 +111,7 @@ darwin-rebuild build --flake .#johno-macbookpro
 - `nix-book`: Compact laptop with storage constraints, uses `home/home-laptop-compact.nix`
 - `boxy`: Shared living room media center/gaming desktop with AMD GPU, uses `home/home-media-center.nix`
 - `zix790prors`: Powerful all-purpose workstation (gaming, 3D modeling, development), dual-boots Windows 11 with shared btrfs /games partition, uses `home/home-desktop.nix`
+- `wixos`: WSL2 development environment running in Windows partition of zix790prors, uses `home/home-desktop.nix`
 - `live-usb`: Bootable ISO configuration, uses `home/home-live-usb.nix`
 - `johno-macbookpro`: macOS work laptop, uses `home/home-darwin-work.nix`
 

flake.lock

@@ -60,6 +60,22 @@
         "type": "github"
       }
     },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1765121682,
+        "narHash": "sha256-4VBOP18BFeiPkyhy9o4ssBNQEvfvv1kXkasAYd0+rrA=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "65f23138d8d09a92e30f1e5c87611b23ef451bf3",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
     "flake-utils": {
       "inputs": {
         "systems": "systems"
@@ -225,18 +241,38 @@
         "type": "github"
       }
     },
-    "nixpkgs": {
+    "nixos-wsl": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "nixpkgs": "nixpkgs"
+      },
       "locked": {
-        "lastModified": 1767480499,
+        "lastModified": 1765841014,
-        "narHash": "sha256-8IQQUorUGiSmFaPnLSo2+T+rjHtiNWc+OAzeHck7N48=",
+        "narHash": "sha256-55V0AJ36V5Egh4kMhWtDh117eE3GOjwq5LhwxDn9eHg=",
-        "owner": "nixos",
+        "owner": "nix-community",
-        "repo": "nixpkgs",
+        "repo": "NixOS-WSL",
-        "rev": "30a3c519afcf3f99e2c6df3b359aec5692054d92",
+        "rev": "be4af8042e7a61fa12fda58fe9a3b3babdefe17b",
         "type": "github"
       },
       "original": {
-        "owner": "nixos",
+        "owner": "nix-community",
-        "ref": "nixos-25.11",
+        "ref": "main",
+        "repo": "NixOS-WSL",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1765472234,
+        "narHash": "sha256-9VvC20PJPsleGMewwcWYKGzDIyjckEz8uWmT0vCDYK0=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "2fbfb1d73d239d2402a8fe03963e37aab15abe8b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
         "repo": "nixpkgs",
         "type": "github"
       }
@@ -257,6 +293,22 @@
         "type": "github"
       }
     },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1767480499,
+        "narHash": "sha256-8IQQUorUGiSmFaPnLSo2+T+rjHtiNWc+OAzeHck7N48=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "30a3c519afcf3f99e2c6df3b359aec5692054d92",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
     "plasma-manager": {
       "inputs": {
         "home-manager": [
@@ -312,7 +364,8 @@
         "jovian": "jovian",
         "nix-darwin": "nix-darwin",
         "nix-doom-emacs-unstraightened": "nix-doom-emacs-unstraightened",
-        "nixpkgs": "nixpkgs",
+        "nixos-wsl": "nixos-wsl",
+        "nixpkgs": "nixpkgs_2",
         "nixpkgs-unstable": "nixpkgs-unstable",
         "plasma-manager": "plasma-manager",
         "plasma-manager-unstable": "plasma-manager-unstable"

flake.nix

@@ -4,6 +4,7 @@
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";
     nixpkgs-unstable.url = "github:nixos/nixpkgs/nixos-unstable";
+    nixos-wsl.url = "github:nix-community/NixOS-WSL/main";
     
     nix-darwin = {
       url = "github:nix-darwin/nix-darwin/nix-darwin-25.11";
@@ -54,7 +55,7 @@
     };
   };
 
-  outputs = { self, nixpkgs, nixpkgs-unstable, ... } @ inputs: let
+  outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, ... } @ inputs: let
     # Shared overlay function to reduce duplication across module sets
     # Parameters:
     #   unstableOverlays: Additional overlays to apply when importing nixpkgs-unstable
@@ -83,7 +84,6 @@
       };
     };
 
-
     nixosModules = [
       ./roles
       inputs.home-manager.nixosModules.home-manager
@@ -157,10 +157,24 @@
       ];
     };
 
+    nixosConfigurations.wixos = nixpkgs.lib.nixosSystem rec {
+      system = "x86_64-linux";
+      modules = nixosModules ++ [
+        nixos-wsl.nixosModules.default
+        ./machines/wixos/configuration.nix
+        inputs.home-manager.nixosModules.home-manager
+        {
+          home-manager.users.johno = import ./home/home-desktop.nix;
+          home-manager.extraSpecialArgs = { inherit system; };
+        }
+      ];
+    };
+
     nixosConfigurations.zix790prors = nixpkgs.lib.nixosSystem rec {
       system = "x86_64-linux";
       modules = nixosModules ++ [
         ./machines/zix790prors/configuration.nix
+        inputs.home-manager.nixosModules.home-manager
         {
           home-manager.users.johno = import ./home/home-desktop.nix;
           home-manager.extraSpecialArgs = { inherit system; };

home/roles/development/skills/beads_implement.md

@@ -54,8 +54,6 @@ When this command is invoked:
    - Read `thoughts/beads-{bead-id}/plan.md` FULLY
    - Check for any existing checkmarks (- [x]) indicating partial progress
    - Read any research at `thoughts/beads-{bead-id}/research.md`
-   - If plan's Success Criteria references contribution guidelines (e.g., "Per CONTRIBUTING.md:"),
-     verify the original CONTRIBUTING.md still exists and requirements are current
 
 5. **Mark bead in progress** (if not already):
    ```bash
@@ -129,10 +127,6 @@ All phases completed and automated verification passed:
 - {List manual verification items from plan}
 
 Let me know when manual testing is complete so I can close the bead.
-
-**Contribution guidelines compliance:**
-- {List any contribution guideline requirements that were part of Success Criteria}
-- {Note if any requirements could not be automated and need manual review}
 ```
 
 **STOP HERE and wait for user confirmation.**

home/roles/development/skills/beads_plan.md

@@ -51,32 +51,13 @@ When this command is invoked:
    - Any linked tickets or docs
    - Use Read tool WITHOUT limit/offset
 
-2. **Check for contribution guidelines**:
+2. **Spawn initial research tasks**:
-
-   ```bash
-   # Check standard locations for contribution guidelines
-   for f in CONTRIBUTING.md .github/CONTRIBUTING.md docs/CONTRIBUTING.md; do
-     if [ -f "$f" ]; then
-       echo "Found: $f"
-       break
-     fi
-   done
-   ```
-
-   If found:
-   - Read the file fully
-   - Extract actionable requirements (testing, code style, documentation, PR conventions)
-   - These requirements MUST be incorporated into the plan's Success Criteria
-
-   If not found, note "No contribution guidelines found" and proceed.
-
-3. **Spawn initial research tasks**:
    - **codebase-locator**: Find all files related to the task
    - **codebase-analyzer**: Understand current implementation
    - **codebase-pattern-finder**: Find similar features to model after
    - **thoughts-locator**: Find any existing plans or decisions
 
-4. **Read all files identified by research**:
+3. **Read all files identified by research**:
    - Read them FULLY into main context
    - Cross-reference with requirements
 
@@ -292,12 +273,6 @@ Always separate into two categories:
 - Performance under real conditions
 - Edge cases hard to automate
 
-**From Contribution Guidelines** (if CONTRIBUTING.md exists):
-- Include any testing requirements specified in guidelines
-- Include any code style/linting requirements
-- Include any documentation requirements
-- Reference the guideline: "Per CONTRIBUTING.md: {requirement}"
-
 ## Example Invocation
 
 ```

home/roles/development/skills/beads_research.md

@@ -51,18 +51,6 @@ When this command is invoked:
 - Use the Read tool WITHOUT limit/offset parameters
 - Read these files yourself in the main context before spawning sub-tasks
 
-### Step 1.5: Check for contribution guidelines
-
-Before spawning sub-agents, check if the repository has contribution guidelines:
-
-```bash
-for f in CONTRIBUTING.md .github/CONTRIBUTING.md docs/CONTRIBUTING.md; do
-  if [ -f "$f" ]; then echo "Found: $f"; break; fi
-done
-```
-
-If found, read the file and note key requirements. These should be included in the research document under a "## Contribution Guidelines" section if relevant to the research question.
-
 ### Step 2: Analyze and decompose the research question
 - Break down the query into composable research areas
 - Identify specific components, patterns, or concepts to investigate
@@ -155,10 +143,6 @@ status: complete
 ## Architecture Documentation
 {Current patterns, conventions found in codebase}
 
-## Contribution Guidelines
-{If CONTRIBUTING.md exists, summarize key requirements relevant to the research topic}
-{If no guidelines found, omit this section}
-
 ## Historical Context (from thoughts/)
 {Relevant insights from thoughts/ with references}
 

home/roles/development/skills/parallel_beads.md

@@ -68,12 +68,10 @@ Work on bead [BEAD_ID]: [BEAD_TITLE]
      - Read the plan and find the "Automated Verification" section
      - Extract each verification command (lines starting with `- [ ]` followed by a command)
      - Example: `- [ ] Tests pass: \`make test\`` → extract `make test`
-     - Note any "Per CONTRIBUTING.md:" requirements for additional validation
    - If no plan exists, use best-effort validation:
      - Check if `Makefile` exists → try `make test` and `make lint`
      - Check if `flake.nix` exists → try `nix flake check`
      - Check if `package.json` exists → try `npm test`
-     - **Check for CONTRIBUTING.md** → read and extract testing/linting requirements
      - If none found, note "No validation criteria found"
 
 4. **Implement the changes**:

machines/wixos/configuration.nix

@@ -0,0 +1,56 @@
+# Edit this configuration file to define what should be installed on
+# your system. Help is available in the configuration.nix(5) man page, on
+# https://search.nixos.org/options and in the NixOS manual (`nixos-help`).
+
+# NixOS-WSL specific options are documented on the NixOS-WSL repository:
+# https://github.com/nix-community/NixOS-WSL
+
+{ config, lib, pkgs, ... }:
+
+{
+  imports = [
+  ];
+
+  roles = {
+    audio.enable = true;
+    desktop = {
+      enable = true;
+      wayland = true;
+    };
+    nvidia = {
+      enable = true;
+      package = "latest";
+      graphics.extraPackages = with pkgs; [
+        mesa
+        libvdpau-va-gl
+        libva-vdpau-driver
+      ];
+    };
+    users.enable = true;
+  };
+
+  networking.hostName = "wixos";
+
+  wsl.enable = true;
+  wsl.defaultUser = "johno";
+  wsl.startMenuLaunchers = true;
+  wsl.useWindowsDriver = true;
+  wsl.wslConf.network.hostname = "wixos";
+  wsl.wslConf.user.default = "johno";
+
+  # WSL-specific environment variables for graphics
+  environment.sessionVariables = {
+    LD_LIBRARY_PATH = [
+      "/usr/lib/wsl/lib"
+      "/run/opengl-driver/lib"
+    ];
+  };
+
+  # This value determines the NixOS release from which the default
+  # settings for stateful data, like file locations and database versions
+  # on your system were taken. It's perfectly fine and recommended to leave
+  # this value at the release version of the first install of this system.
+  # Before changing this value read the documentation for this option
+  # (e.g. man configuration.nix or on https://nixos.org/nixos/options.html).
+  system.stateVersion = "24.05"; # Did you read the comment?
+}

scripts/rotate-wallpaper.sh

@@ -1,6 +1,30 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --help|-h)
+            echo "Usage: $0 [OPTIONS]"
+            echo ""
+            echo "Rotate to the next wallpaper in the configured list."
+            echo ""
+            echo "This script increments the currentIndex in home/wallpapers/default.nix,"
+            echo "cycling through available wallpapers. Rebuild your system to apply"
+            echo "the new wallpaper."
+            echo ""
+            echo "Options:"
+            echo "  --help, -h    Show this help message"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Use --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'

scripts/update-doomemacs.sh

@@ -1,6 +1,30 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --help|-h)
+            echo "Usage: $0 [OPTIONS]"
+            echo ""
+            echo "Update Doom Emacs to the latest commit from the doomemacs repository."
+            echo ""
+            echo "This script fetches the latest commit SHA from the default branch,"
+            echo "updates the rev and sha256 in home/roles/emacs/default.nix, and"
+            echo "prepares the configuration for a system rebuild."
+            echo ""
+            echo "Options:"
+            echo "  --help, -h    Show this help message"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Use --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'

scripts/upgrade.sh

@@ -1,6 +1,35 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --help|-h)
+            echo "Usage: $0 [OPTIONS]"
+            echo ""
+            echo "Perform a major upgrade of the NixOS configuration."
+            echo ""
+            echo "This script runs the following steps:"
+            echo "  1. Update all flake inputs (nix flake update)"
+            echo "  2. Update Doom Emacs to the latest commit"
+            echo "  3. Update Claude Code to the latest version"
+            echo "  4. Rotate to the next wallpaper"
+            echo ""
+            echo "After completion, review changes with 'git diff' and rebuild"
+            echo "your system with 'sudo nixos-rebuild switch --flake .'"
+            echo ""
+            echo "Options:"
+            echo "  --help, -h    Show this help message"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Use --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'