chore: Add CLAUDE.md

Author: edmundmiller

CLAUDE.md

@@ -10,23 +10,31 @@ This is a Nix-based dotfiles repository using Flakes for managing system configu
 
 ## Essential Commands
 
-All system management is done through the `hey` command (located in `bin/hey`), which wraps a justfile:
+System management can be done through the `hey` command (located in `bin/hey`) or directly with darwin-rebuild:
 
 ```bash
+# Using hey wrapper (if available):
 hey rebuild      # Rebuild and switch to new configuration (alias: hey re)
 hey upgrade      # Update flake inputs and rebuild
 hey rollback     # Roll back to previous generation
 hey gc           # Run garbage collection
 hey check        # Run flake checks
 hey show         # Show flake outputs
 hey test         # Quick rebuild without adding to bootloader
+
+# Direct darwin-rebuild commands:
+sudo darwin-rebuild switch -I darwin=.  # Rebuild and switch to new configuration
+sudo darwin-rebuild switch --flake .    # Alternative flake syntax
+darwin-rebuild --list-generations       # List available generations
+sudo darwin-rebuild --rollback          # Roll back to previous generation
+nix-collect-garbage -d                  # Garbage collection
 ```
 
 For development:
 ```bash
-hey shell <package>  # Start nix shell with package
-hey repl            # Start nix repl with flake
-hey search <term>   # Search for packages
+hey shell <package>  # Start nix shell with package (or: nix shell nixpkgs#<package>)
+hey repl            # Start nix repl with flake (or: nix repl)
+hey search <term>   # Search for packages (or: nix search nixpkgs <term>)
 ```
 
 ## Architecture
@@ -76,14 +84,14 @@ in {
 
 ### Testing Configuration Changes
 1. Make changes to relevant files
-2. Run `hey test` for quick testing (doesn't update boot)
-3. Run `hey rebuild` to apply permanently
-4. If issues occur: `hey rollback`
+2. Run `sudo darwin-rebuild switch -I darwin=.` to rebuild and switch
+3. If issues occur: `sudo darwin-rebuild --rollback`
 
 ### Updating Dependencies
 ```bash
-hey upgrade          # Update all flake inputs
-nix flake update    # Update specific input
+nix flake update                               # Update all flake inputs
+nix flake update <input>                       # Update specific input
+sudo darwin-rebuild switch -I darwin=.        # Apply updates
 ```
 
 ### Adding New Packages
@@ -108,7 +116,8 @@ nix flake update    # Update specific input
 
 ## Notes
 
-- The `hey` command must be run from the repository root
-- After major updates, run `hey gc` to clean old generations
+- Commands must be run from the repository root
+- After major updates, run `nix-collect-garbage -d` to clean old generations
 - Host-specific settings override module defaults
-- The system uses home-manager for user-level configuration
+- The system uses home-manager for user-level configuration
+- The `hey` command (if available) provides convenient wrappers for common operations

bin/hey

@@ -1,6 +1,5 @@
 #!/usr/bin/env cached-nix-shell
-#! nix-shell -i "just --justfile" --quiet
-#! nix-shell -p just
+#! nix-shell -p just -i "just --justfile" --quiet
 
 # Nix's CLI has a poor user story, in my opinion. It could be better; Guix is a
 # good role model here. I wrote this script to abstract the more common
@@ -13,7 +12,7 @@
 # are often and easily forgotten. This spares me that fumbling phase and also
 # serves as a reference.
 
-FLAKE := "../"
+FLAKE := "."
 HOST := ""
 # FIXME HOST := env_var('HOST')
 
@@ -49,9 +48,15 @@ rebuild +ARGS='switch':
     shift
   fi
   set -x
-  sudo nixos-rebuild \
-    --flake {{FLAKE}} \
-    --option pure-eval no {{ARGS}} "$@"
+  if [[ "$(uname)" == "Darwin" ]]; then
+    sudo darwin-rebuild \
+      -I darwin={{FLAKE}} \
+      {{ARGS}} "$@"
+  else
+    sudo nixos-rebuild \
+      --flake {{FLAKE}} \
+      --option pure-eval no {{ARGS}} "$@"
+  fi
 
 repl:
   #!/usr/bin/env bash
@@ -88,8 +93,17 @@ show:
   rebuild --fast test {{ARGS}}
 
 rollback:
+  #!/usr/bin/env bash
   # Roll back to last generation
-  rebuild --rollback switch
+  if [[ "$(uname)" == "Darwin" ]]; then
+    sudo darwin-rebuild --rollback
+  else
+    rebuild --rollback switch
+  fi
+
+gc:
+  # Run garbage collection
+  nix-collect-garbage -d
 
 alias u := update
 
@@ -112,6 +126,10 @@ update +FLAKES='':
   # Search nixpkgs for a package
   nix search nixpkgs {{QUERY}}
 
+@shell PACKAGE:
+  # Start nix shell with package
+  nix shell nixpkgs#{{PACKAGE}}
+
 @swap PATHS:
   #!/usr/bin/env bash
   # Recursively swap nix-store symlinks with copies (or back).