diff --git a/Brewfile b/Brewfile
index 9cf0a03..071c6ab 100644
--- a/Brewfile
+++ b/Brewfile
@@ -1,3 +1,4 @@
+brew 'stow'
 brew 'git-delta'
 brew 'herdr'
 cask 'wezterm'
diff --git a/Makefile b/Makefile
index 5e45a22..6202a96 100644
--- a/Makefile
+++ b/Makefile
@@ -1,84 +1,40 @@
 .DEFAULT_GOAL := help
 
+STOW_PACKAGES ?= bash fastfetch git herdr lazygit nvim wezterm yazi zsh
+
 .PHONY: help
 help:
 	@echo "Dotfiles Setup Commands:"
 	@echo ""
 	@echo "Initial Setup:"
-	@echo "  make install-nix          - Install Nix package manager"
-	@echo "  make setup-home-manager   - Bootstrap home-manager (first time setup)"
-	@echo "  make setup-mac            - Full setup for macOS (Nix + home-manager + Homebrew)"
-	@echo "  make setup-linux          - Full setup for Linux (Nix + home-manager)"
-	@echo "  make setup-wsl-nixos      - Link NixOS configuration for WSL2 (requires sudo)"
+	@echo "  make setup-mac            - Install Brewfile packages and Stow dotfiles + AeroSpace"
+	@echo "  make setup-arch           - Install pacman list and Stow dotfiles"
+	@echo "  make stow                 - Symlink STOW_PACKAGES into your home directory"
+	@echo "  make setup-wsl-nixos      - Stage NixOS WSL2 from an existing checkout (sudo)"
 	@echo ""
 	@echo "NixOS WSL2 Commands:"
 	@echo "  make switch               - Rebuild NixOS system (slow, needs sudo)"
-	@echo "  make home-switch          - Rebuild home-manager only (fast, no sudo)"
 	@echo "  make build                - Build system without switching (test config)"
 	@echo "  make update               - Update flake inputs"
 	@echo "  make upgrade              - Update flake inputs and rebuild"
 	@echo "  make generations          - List system generations"
-	@echo "  make home-generations     - List home-manager generations"
 	@echo "  make gc                   - Run garbage collection"
 	@echo "  make clean                - Deep clean (delete old generations + gc)"
 	@echo ""
 	@echo "Other Commands:"
 	@echo "  make set-default-shell    - Set zsh as default shell (requires sudo)"
 	@echo "  make install-brew         - Install Homebrew (macOS only)"
-	@echo "  make install-brew-packages- Install GUI apps via Homebrew (macOS only)"
+	@echo "  make install-brew-packages - Install packages from Brewfile (macOS only)"
+	@echo "  make install-arch-packages - Upgrade Arch and install pacman-packages.txt"
 	@echo ""
 
-.PHONY: install-nix
-install-nix:
-	@echo "Installing Nix package manager..."
-	curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-
-.PHONY: setup-home-manager
-setup-home-manager:
-	@echo "Activating home-manager configuration..."
-	@echo "Detecting system..."
-	@if [ "$$(uname -s)" = "Darwin" ]; then \
-		if [ "$$(uname -m)" = "arm64" ]; then \
-			echo "Detected: macOS Apple Silicon"; \
-			nix run nix-darwin -- switch --flake .#aarch64; \
-		else \
-			echo "Detected: macOS Intel"; \
-			nix run nix-darwin -- switch --flake .#x86_64; \
-		fi \
-	else \
-		if [ "$$(uname -m)" = "x86_64" ]; then \
-			echo "Detected: Linux x86_64"; \
-			nix run home-manager/master -- switch --flake .#$$USER-x86_64-linux; \
-		else \
-			echo "Detected: Linux ARM64"; \
-			nix run home-manager/master -- switch --flake .#$$USER-aarch64-linux; \
-		fi \
-	fi
-
-.PHONY: update-home-manager
-update-home-manager:
-	@echo "Updating home-manager configuration..."
-	@if [ "$$(uname -s)" = "Darwin" ]; then \
-		if [ "$$(uname -m)" = "arm64" ]; then \
-			darwin-rebuild switch --flake .#aarch64; \
-		else \
-			darwin-rebuild switch --flake .#x86_64; \
-		fi \
-	else \
-		if [ "$$(uname -m)" = "x86_64" ]; then \
-			nix run home-manager/master -- switch --flake .#$$USER-x86_64-linux; \
-		else \
-			nix run home-manager/master -- switch --flake .#$$USER-aarch64-linux; \
-		fi \
-	fi
-
 .PHONY: set-default-shell
 set-default-shell:
 	@echo "Setting zsh as default shell..."
 	@echo "This requires sudo access to modify /etc/shells"
 	@ZSH_PATH=$$(which zsh); \
 	if [ -z "$$ZSH_PATH" ]; then \
-		echo "Error: zsh not found. Run 'make setup-home-manager' first."; \
+		echo "Error: zsh not found. Install it with your OS package manager first."; \
 		exit 1; \
 	fi; \
 	echo "Found zsh at: $$ZSH_PATH"; \
@@ -102,19 +58,26 @@ install-brew:
 .PHONY: install-brew-packages
 install-brew-packages:
 	@echo "Installing Homebrew packages..."
-	brew bundle
+	brew bundle --file=Brewfile
+
+.PHONY: install-arch-packages
+install-arch-packages:
+	@echo "Upgrading Arch Linux and installing packages..."
+	sudo pacman -Syu --needed - < pacman-packages.txt
+
+.PHONY: stow
+stow:
+	stow --dir="$(CURDIR)" --target="$(HOME)" $(STOW_PACKAGES)
 
 .PHONY: setup-mac
-setup-mac: install-nix setup-home-manager install-brew install-brew-packages
-	@echo ""
-	@echo "✅ macOS setup complete!"
-	@echo "Packages installed via Nix, GUI apps installed via Homebrew"
+setup-mac: install-brew-packages
+	$(MAKE) stow STOW_PACKAGES="$(STOW_PACKAGES) aerospace"
+	@echo "Brewfile packages installed and macOS dotfiles linked."
 
-.PHONY: setup-linux
-setup-linux: install-nix setup-home-manager
-	@echo ""
-	@echo "✅ Linux setup complete!"
-	@echo "All packages and configs installed via Nix"
+.PHONY: setup-arch
+setup-arch: install-arch-packages
+	$(MAKE) stow
+	@echo "Pacman packages installed and Arch Linux dotfiles linked."
 
 .PHONY: setup-wsl-nixos
 setup-wsl-nixos:
@@ -142,11 +105,6 @@ switch:
 	@echo "Rebuilding NixOS system..."
 	sudo nixos-rebuild switch --flake .#nixos-wsl
 
-.PHONY: home-switch
-home-switch:
-	@echo "Rebuilding home-manager configuration..."
-	nix run home-manager/master -- switch --flake .#nixos-wsl
-
 .PHONY: build
 build:
 	@echo "Building NixOS system (without switching)..."
@@ -166,11 +124,6 @@ generations:
 	@echo "System generations:"
 	sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
 
-.PHONY: home-generations
-home-generations:
-	@echo "Home-manager generations:"
-	nix run home-manager/master -- generations
-
 .PHONY: gc
 gc:
 	@echo "Running garbage collection..."
@@ -182,7 +135,4 @@ clean:
 	@echo "Deep cleaning old generations and running garbage collection..."
 	@echo "Deleting system generations older than 7 days..."
 	sudo nix-collect-garbage --delete-older-than 7d
-	@echo "Deleting home-manager generations older than 7 days..."
-	nix run home-manager/master -- expire-generations "-7 days"
 	@echo "✅ Deep clean complete!"
-
diff --git a/README b/README
index c3ec2cb..0e672f2 100644
--- a/README
+++ b/README
@@ -1,12 +1,48 @@
-Fully Reproducible dotfiles config
+Dotfiles
+========
 
-"Dotfiles managed by Nix: because spending 40 hours to save 4 minutes is a lifestyle. Fully reproducible - I've tested it on my Windows gaming rig (NixOS-WSL2), my wife's MacBook Air, and my own laptop (I use Arch BTW). If it works there, it'll work anywhere."
+Shared application configuration with platform-specific package management:
 
-Follows the XDG Base Directory Specification - keeping your home directory clean and uncluttered by organizing all configuration files in ~/.config instead of scattering dotfiles everywhere.
+  NixOS WSL2 / native NixOS   Nix flakes + integrated Home Manager
+  macOS                      Homebrew Bundle (Brewfile) + GNU Stow
+  Arch Linux                 pacman (pacman-packages.txt) + GNU Stow
 
-For Nix setup and usage, see docs/README.nix.md.
+Nix is only used for NixOS. There are no macOS or standalone Linux Home
+Manager configurations. The native package lists are smaller than the NixOS
+development environment; they do not install every configured application.
 
-FAQ
+Most application configs live under .config in Stow-compatible directories.
+Zsh and Bash startup files live directly in the home directory. Symlinks keep
+the checkout editable; application config changes take effect after reloading
+the application, without a Nix rebuild.
 
-Q: Why Nix?
-A: Because I like pain and reproducibility.
+Getting started
+---------------
+
+Read docs/DEPLOYMENT.md first for prerequisites, shell dependencies, existing
+file conflicts, and native NixOS hardware customization.
+
+From a checkout at ~/dotfiles:
+
+  macOS:       make setup-mac     (requires Homebrew on PATH)
+  Arch Linux:  make setup-arch    (requires sudo and pacman)
+
+For a fresh, already installed NixOS-WSL distribution:
+
+  nix --extra-experimental-features 'nix-command flakes' run github:user3301/dotfiles#bootstrap-wsl
+
+For ongoing NixOS WSL updates: make switch
+For native NixOS: sudo nixos-rebuild switch --flake .#nixos-native
+Both NixOS configurations use /home/user3301/dotfiles.
+
+Documentation
+-------------
+
+  docs/DEPLOYMENT.md              Installation, migration, and local settings
+  docs/QUICK_REFERENCE.md         Common commands
+  docs/ARCHITECTURE.md            Source layout, modules, and CI
+  docs/README.nix.md              NixOS usage and maintenance
+  docs/EXAMPLE-VERSION-PINNING.md  The Nix package pins used by this repo
+  docs/IMPLEMENTATION_SUMMARY.md  Current platform support and boundaries
+  git/.config/git/README.md       Git identity and SSH commit signing
+  nvim/.config/nvim/README.md     LazyVim and language-server setup
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 2a33e1c..8b5c579 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,481 +1,130 @@
 # Dotfiles Architecture
 
-## Design Philosophy
-
-This dotfiles repository is designed with the following principles:
-
-1. **Reproducibility**: Identical environments across different machines and platforms
-2. **Modularity**: Shared code between platforms, platform-specific overrides where needed
-3. **Flexibility**: Support both NixOS (system-level) and non-NixOS (user-level) configurations
-4. **Compatibility**: Preserve existing GNU Stow-compatible structure
-5. **Separation of Concerns**: System configuration vs. user configuration
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        flake.nix                            │
-│              (Entry point, defines all outputs)             │
-└─────────────────────────────────────────────────────────────┘
-                            │
-        ┌───────────────────┼───────────────────┐
-        │                   │                   │
-        ▼                   ▼                   ▼
-┌──────────────┐   ┌──────────────┐   ┌──────────────┐
-│   NixOS      │   │  Standalone  │   │  nix-darwin  │
-│ Configuration│   │    Home      │   │   (macOS)    │
-│              │   │   Manager    │   │              │
-└──────────────┘   └──────────────┘   └──────────────┘
-        │                   │                   │
-        ▼                   ▼                   ▼
-┌──────────────┐   ┌──────────────┐   ┌──────────────┐
-│ system cfg + │   │  home cfg    │   │ system cfg + │
-│  home cfg    │   │    only      │   │  home cfg    │
-└──────────────┘   └──────────────┘   └──────────────┘
-        │                   │                   │
-        └───────────────────┼───────────────────┘
-                            │
-                            ▼
-                ┌───────────────────────┐
-                │   Home Manager        │
-                │   Modules (Shared)    │
-                │                       │
-                │ • common.nix          │
-                │ • shell.nix           │
-                │ • dev-tools.nix       │
-                │ • neovim.nix          │
-                │ • terminal.nix        │
-                └───────────────────────┘
-                            │
-                            ▼
-                ┌───────────────────────┐
-                │   Existing Dotfiles   │
-                │   (Symlinked)         │
-                │                       │
-                │ • nvim/.config/nvim   │
-                │ • herdr/.config/...   │
-                │ • wezterm/.config/... │
-                │ • etc.                │
-                └───────────────────────┘
-```
-
-## Layer Breakdown
-
-### Layer 1: Flake Entry Point
-
-**File**: `/Users/gaiz/dotfiles/flake.nix`
-
-- Defines all inputs (nixpkgs, home-manager, nixos-wsl, nix-darwin)
-- Provides outputs for different configurations
-- Contains helper functions (`mkSystem`, `mkHome`, `mkDarwin`)
-
-**Outputs**:
-- `nixosConfigurations.nixos-wsl`: WSL2 system + home config
-- `nixosConfigurations.nixos-native`: Native NixOS system + home config
-- `homeConfigurations.user@linux`: Standalone home config for Archlinux
-- `darwinConfigurations.aarch64`: macOS system + home config
-
-### Layer 2: System Configurations
-
-**Purpose**: System-level settings (only on NixOS and macOS)
-
-**Files**:
-- `systems/wsl/configuration.nix`: WSL2-specific system config
-- `systems/native/configuration.nix`: Native NixOS system config
-- `systems/darwin/configuration.nix`: macOS system config (via nix-darwin)
-
-**Responsibilities**:
-- Boot configuration (native NixOS only)
-- User account creation
-- System packages (minimal)
-- System services (SSH, networking, etc.)
-- Platform-specific settings (WSL interop, macOS defaults, etc.)
-
-**Key Decision**: Keep system packages minimal. Most packages go in Home Manager.
-
-### Layer 3: Home Manager Configurations
-
-**Purpose**: User-level settings and packages
-
-**Files**:
-- `home/nixos-wsl.nix`: WSL2 user config
-- `home/nixos-native.nix`: Native NixOS user config
-- `home/archlinux.nix`: Archlinux user config
-- `home/darwin.nix`: macOS user config
-
-**Responsibilities**:
-- Import shared modules
-- Set username and home directory
-- Platform-specific packages
-- Platform-specific overrides
-- Git user configuration
-
-### Layer 4: Shared Modules
-
-**Purpose**: Reusable configuration modules
-
-**Files** in `home/modules/`:
-
-1. **common.nix**: Base configuration
-   - Home Manager self-management
-   - XDG directory structure
-   - State version
-   - Unfree packages allowance
-   - Common environment variables
-   - Minimal base packages
-
-2. **shell.nix**: Shell configuration
-   - Zsh with plugins
-   - Sources existing .zshrc and .zshenv
-   - Bash fallback
-
-3. **dev-tools.nix**: Development packages
-   - Git, gh, lazygit
-   - Modern CLI tools (ripgrep, fd, bat, etc.)
-   - Build tools
-   - Nix development tools
-
-4. **neovim.nix**: Neovim configuration
-   - Enables neovim as default editor
-   - Installs LSP servers and formatters
-   - Symlinks existing nvim config
-
-5. **terminal.nix**: Terminal multiplexers and emulators
-   - Herdr configuration
-   - Wezterm configuration
-   - Yazi file manager
-   - Symlinks to existing configs
-
-**Design Pattern**: Each module is self-contained and can be independently enabled/disabled by commenting out the import.
-
-### Layer 5: Existing Dotfiles
-
-**Purpose**: Actual application configurations
-
-**Structure**:
-```
-app-name/
-  .config/
-    app-name/
-      config-files
-```
-
-This structure is compatible with GNU Stow and is symlinked by Home Manager using `mkOutOfStoreSymlink`.
-
-**Why symlink instead of copy?**
-- Allows editing configs directly without rebuilding
-- Keeps configs in familiar locations
-- Maintains git history in dotfiles repo
-- Compatible with manual management if needed
-
-## Configuration Flow
-
-### NixOS WSL2 Deployment
-
-```
-1. User runs: sudo nixos-rebuild switch --flake .#nixos-wsl
-                                              │
-2. Nix evaluates flake.nix ─────────────────┘
-                │
-3. Loads nixosConfigurations.nixos-wsl
-                │
-4. Applies systems/wsl/configuration.nix
-   - Creates user3301
-   - Configures WSL settings
-   - Enables zsh
-                │
-5. Loads Home Manager module (integrated)
-                │
-6. Evaluates home/nixos-wsl.nix
-   - Sets username/home directory
-   - Imports shared modules
-                │
-7. Each module does its job
-   - Installs packages
-   - Configures programs
-   - Creates symlinks to existing dotfiles
-                │
-8. System is now configured!
-```
-
-### Archlinux Deployment
-
-```
-1. User runs: home-manager switch --flake .#user@linux
-                                           │
-2. Nix evaluates flake.nix ───────────────┘
-                │
-3. Loads homeConfigurations.user@linux
-                │
-4. Evaluates home/archlinux.nix
-   - Sets username/home directory
-   - Enables genericLinux target
-   - Imports shared modules
-                │
-5. Each module does its job
-   - Installs packages (to Nix profile)
-   - Configures programs
-   - Creates symlinks to existing dotfiles
-                │
-6. User environment is now configured!
-   (System packages still managed by pacman)
-```
-
-## Key Architectural Decisions
-
-### 1. Why separate system and home configurations?
-
-**Reason**: Enables both full NixOS systems and non-NixOS systems (Archlinux) to share the same user-level configuration.
-
-**Trade-off**: Slightly more complex structure, but much more flexible.
-
-### 2. Why use mkOutOfStoreSymlink?
-
-**Reason**: Allows editing dotfiles directly without Nix rebuilds. Configs remain in version control and can be modified interactively.
-
-**Alternative**: Use `home.file."path".source = ./path` to copy files into Nix store (immutable, requires rebuild to change).
-
-### 3. Why minimal system packages?
-
-**Reason**:
-- Portability: Same packages work on NixOS and non-NixOS
-- Rollback: Home Manager rollbacks are faster and don't affect system
-- Separation: Clear boundary between system and user concerns
-
-**Exception**: System services and daemons should be in system config.
-
-### 4. Why not use nix-darwin for everything on macOS?
-
-**Reason**: Some macOS applications (especially GUI apps) are better managed via Homebrew due to notarization, automatic updates, and integration with macOS app store.
-
-**Hybrid approach**:
-- nix-darwin for system settings and CLI tools
-- Homebrew for GUI applications (Brewfile)
-- Home Manager for user-level dotfiles
-
-### 5. Why flakes instead of channels?
-
-**Reason**:
-- **Reproducibility**: Flakes pin exact versions (flake.lock)
-- **Composability**: Easy to combine inputs
-- **Portability**: Self-contained, no channel state
-- **Modern**: Official Nix direction
-
-**Trade-off**: Requires Nix 2.4+ and experimental features enabled.
-
-## Module Interaction
-
-### Dependency Graph
-
-```
-common.nix (base, required)
-    │
-    ├── shell.nix (depends on common for home.homeDirectory)
-    │       │
-    │       └── Sources existing zsh configs
-    │
-    ├── dev-tools.nix (standalone)
-    │       │
-    │       └── Provides tools for other modules (gcc, etc.)
-    │
-    ├── neovim.nix (depends on dev-tools for LSPs)
-    │       │
-    │       └── Symlinks existing nvim config
-    │
-    └── terminal.nix (standalone)
-            │
-            └── Symlinks existing terminal configs
-```
-
-### Avoiding Circular Dependencies
-
-- **common.nix** has no dependencies
-- **shell.nix** only reads from common
-- Other modules can depend on common and dev-tools
-- No module depends on terminal (it's a leaf node)
-
-### Override Mechanism
-
-Platform-specific configs can override any module setting:
-
-```nix
-# In home/nixos-wsl.nix
-imports = [ ./modules/common.nix ];
-
-# Override a setting from common.nix
-home.sessionVariables.EDITOR = "vim";  # Override from "nvim"
-```
-
-## Extension Points
-
-### Adding a New Platform
-
-1. Create system config (if NixOS-based): `systems/newplatform/configuration.nix`
-2. Create home config: `home/newplatform.nix`
-3. Add to `flake.nix` outputs
-4. Update DEPLOYMENT.md
-
-### Adding a New Module
-
-1. Create `home/modules/newmodule.nix`
-2. Import in relevant platform configs
-3. Document in DEPLOYMENT.md
-
-### Adding Platform-Specific Packages
-
-Option 1: In platform's home config:
-```nix
-# home/nixos-wsl.nix
-home.packages = with pkgs; [ wsl-specific-tool ];
-```
-
-Option 2: Conditional in module:
-```nix
-# home/modules/dev-tools.nix
-home.packages = with pkgs; [
-  git
-] ++ lib.optionals stdenv.isLinux [
-  linux-specific-tool
-];
-```
-
-### Adding System Services (NixOS only)
-
-In system configuration:
-```nix
-# systems/native/configuration.nix
-services.myservice = {
-  enable = true;
-  # configuration
-};
-```
-
-## Security Considerations
-
-### Secrets Management
-
-**Current approach**: Manual management for simplicity
-- Git SSH keys are manually generated on each machine
-- No automated secret management to reduce complexity
-- Sensitive credentials kept outside of version control
-
-**Alternatives** (if needed in the future):
-- **agenix**: Age-encrypted secrets
-- **git-crypt**: Transparent git encryption
-- **Local overrides**: `.zshenv.local` pattern (already in .gitignore)
-
-### Unfree Packages
-
-Currently enabled globally. To restrict:
-
-```nix
-# In relevant config
-nixpkgs.config.allowUnfreePredicate = pkg: builtins.elem (lib.getName pkg) [
-  "vscode"
-  "slack"
-];
-```
-
-## Performance Optimizations
-
-### Build Caching
-
-- **Binary cache**: nixos.org enabled by default
-- **Local cache**: Nix store auto-optimizes with hard links
-- **Flake lock**: Prevents re-downloading unchanged inputs
-
-### Lazy Evaluation
-
-- Modules are only evaluated if imported
-- Unused platform configs don't slow down builds
-- Conditional package installation uses `lib.optionals`
-
-### Garbage Collection
-
-System configs enable automatic GC (weekly, 7-day retention).
-
-Manual GC:
-```bash
-# Delete generations older than 7 days
-nix-collect-garbage --delete-older-than 7d
-
-# Delete all old generations
-nix-collect-garbage -d
-```
-
-## Testing Strategy
-
-### Local Testing
-
-```bash
-# Test without switching
-sudo nixos-rebuild test --flake .#nixos-wsl
-
-# Build without activating
-nix build .#nixosConfigurations.nixos-wsl.config.system.build.toplevel
-
-# Check for errors
-nix flake check
-```
-
-### CI/CD (Future)
-
-Consider GitHub Actions:
-```yaml
-- name: Check flake
-  run: nix flake check
-
-- name: Build all configs
-  run: |
-    nix build .#nixosConfigurations.nixos-wsl.config.system.build.toplevel
-    nix build .#homeConfigurations.user@linux.activationPackage
-```
-
-## Migration Path
-
-### Phase 1: Minimal deployment (current)
-- Basic system config
-- Shared modules for dev tools
-- Symlinks to existing dotfiles
-
-### Phase 2: Enhance modules
-- Add more language-specific tools
-- Configure more applications via Nix
-- Add platform-specific optimizations
-
-### Phase 3: Advanced features
-- Secrets management
-- Custom NixOS modules
-- Per-project development shells (flake.nix in projects)
-
-### Phase 4: Full declarative system
-- All applications via Nix
-- Automated backups
-- Declarative VM configurations
-
-## Troubleshooting
-
-### Common Issues
-
-**Issue**: Symlinks conflict with existing files
-**Solution**: Remove existing files or use `home.file."path".force = true`
-
-**Issue**: Module not found
-**Solution**: Check import path is relative to file location
-
-**Issue**: Infinite recursion
-**Solution**: Check for circular dependencies between modules
-
-**Issue**: Package not found
-**Solution**: Search at search.nixos.org, ensure correct attribute path
-
-## Resources
-
-- **NixOS Manual**: https://nixos.org/manual/nixos/stable/
-- **Home Manager Manual**: https://nix-community.github.io/home-manager/
-- **Nix Pills**: https://nixos.org/guides/nix-pills/
-- **Discourse**: https://discourse.nixos.org/
-
----
-
-This architecture balances **reproducibility**, **flexibility**, and **pragmatism**. It allows you to maintain your existing workflow while gaining the benefits of declarative configuration management.
+## Platform boundaries
+
+Application configuration is shared; package management is not.
+
+```text
+NixOS WSL2 / native                   macOS / Arch Linux
+  flake.nix                            Brewfile / pacman-packages.txt
+    systems/ + home/                     native package installation
+      Home Manager symlinks              GNU Stow symlinks
+                \                        /
+                 shared application files
+```
+
+Only NixOS uses the Nix modules. macOS uses Homebrew Bundle and Stow; Arch Linux
+uses pacman and Stow. Neither native package manifest promises the same package
+set or exact versions as NixOS.
+
+## Repository layout
+
+| Path | Responsibility |
+| --- | --- |
+| `flake.nix`, `flake.lock` | NixOS outputs, pinned inputs, overlays, checks, development shells |
+| `systems/wsl/configuration.nix` | WSL user, interoperability, Docker, nix-ld, system settings |
+| `systems/native/configuration.nix` | Native boot, networking, X11/Qtile/LightDM, SSH |
+| `systems/hardware/hardware-vb.nix` | Currently imported VirtualBox hardware and filesystem config |
+| `home/nixos-wsl.nix`, `home/nixos-native.nix` | User identity, module imports, platform packages |
+| `home/modules/` | Shared NixOS user packages and links |
+| `scripts/bootstrap-nixos-wsl.sh` | One-time NixOS-WSL bootstrap app |
+| `Brewfile`, `pacman-packages.txt` | Native macOS and Arch package lists |
+| `Makefile` | Native package/Stow helpers and NixOS WSL maintenance commands |
+| `.github/workflows/ci.yml` | Quality checks and WSL evaluation |
+| Application directories | Stow-compatible, editable configuration |
+
+Stow packages are `aerospace`, `bash`, `fastfetch`, `git`, `herdr`, `lazygit`,
+`nvim`, `vim`, `wezterm`, `yazi`, and `zsh`. Most use
+`<package>/.config/<application>/`; Bash and Zsh contain home-directory startup
+files. AeroSpace is macOS-only. Vim's XDG config requires explicit loading on
+Vim versions that do not discover it.
+
+## Nix flake
+
+The inputs are `nixpkgs` (NixOS 26.05), `home-manager` (release-26.05),
+`nixos-wsl`, `claude-code-nix`, `herdr`, and a commit-pinned
+`nixpkgs-azure-cli`. `flake.lock` records the resolved revisions.
+
+`mkSystem` adds the Claude Code, Copilot CLI, and Azure CLI overlays to each
+NixOS configuration. Home Manager uses `useGlobalPkgs = true`, so it receives
+those same overlaid packages; `useUserPackages = true` installs home packages
+through the NixOS user profile. The flake passes `inputs` to both module layers.
+See [version pinning](EXAMPLE-VERSION-PINNING.md) for the package exceptions.
+
+| Output | Scope |
+| --- | --- |
+| `nixosConfigurations.nixos-wsl` | x86_64 WSL system and home |
+| `nixosConfigurations.nixos-wsl-bootstrap` | Same WSL configuration plus activation-time checkout creation |
+| `nixosConfigurations.nixos-native` | x86_64 native system and home |
+| `packages.x86_64-linux.bootstrap-wsl` | Packaged bootstrap shell script |
+| `apps.x86_64-linux.bootstrap-wsl` | Runnable bootstrap entry point |
+| `checks.<system>` | Nix quality, Lua format, Zsh syntax, Bash syntax |
+| `formatter.<system>` | nixfmt |
+| `devShells.<system>.default` | Repository editing and lint tools |
+
+The checks, formatter, and development shell support `x86_64-linux` and
+`aarch64-linux`. There is no ARM NixOS host output, no standalone Home Manager
+output, and no Darwin output.
+
+The bootstrap activation creates `/home/user3301/dotfiles` if absent, using a
+Git clone owned by `user3301`. Both normal NixOS homes require that mutable
+checkout; the native output does not create it.
+
+## Home Manager modules
+
+| Module | What it manages |
+| --- | --- |
+| `common.nix` | XDG, Home Manager CLI, editor/DOTFILES session variables, archive/download tools |
+| `shell.nix` | Oh My Zsh, Bash completion, McFly, zoxide, Bash/Zsh startup symlinks |
+| `dev-tools.nix` | CLI/build tools, Kubernetes/Azure tools, Nix tools, Claude Code, Copilot CLI, devcontainer |
+| `git.nix` | Git, gh, Lazygit, delta, GPG agent, Git/Lazygit symlinks, gh SSH protocol |
+| `neovim.nix` | Neovim, language servers, formatters, Tree-sitter tools, fswatch, Neovim symlink |
+| `terminal.nix` | Herdr, Yazi and its integration settings, Herdr/Yazi/Fastfetch symlinks |
+| `wezterm.nix` | WezTerm symlink; imported only by the native home |
+| `languages.nix` | Go, Rust, .NET 8, Protobuf, Python, Node.js toolchains |
+
+The WSL home adds PowerShell and sets `systemd.user.startServices = "suggest"`
+so activation does not try to start user services before a normal WSL login.
+The native home adds GnuPG, WezTerm, and Firefox. NixOS enables Zsh system-wide;
+the shell module links the hand-written startup files rather than generating
+them with Home Manager's shell programs.
+
+## Mutable configuration and reproducibility
+
+Home Manager uses `mkOutOfStoreSymlink` to link application directories or
+startup files into `/home/user3301/dotfiles`. Stow links the same files on macOS
+and Arch Linux. Editing a linked file changes the checkout immediately; reload
+the application to pick it up. Adding a Nix module, package, or link requires a
+NixOS rebuild; adding Stow-managed paths may require rerunning Stow.
+
+Nix pins package sources, not the live contents of these symlinked files.
+System rollback does not roll back mutable dotfiles. Neovim plugins have their
+own `lazy-lock.json` and are downloaded by lazy.nvim, not provisioned by the
+Nix flake. Herdr plugins and credentials are also managed separately.
+
+Git identity/signing overrides and local shell settings are ignored by Git.
+Herdr can write runtime state into its symlinked config directory; `.gitignore`
+excludes those files. See [deployment](DEPLOYMENT.md#local-settings-and-manual-steps).
+
+## Existing CI
+
+`.github/workflows/ci.yml` runs on pushes to `master`, pull requests, and manual
+dispatch. On Ubuntu it lints GitHub Actions, installs Nix, enables a binary
+cache, builds the four `x86_64-linux` checks, and evaluates the WSL system
+derivation:
+
+```sh
+nix build --no-link \
+  .#checks.x86_64-linux.nix-quality \
+  .#checks.x86_64-linux.lua-format \
+  .#checks.x86_64-linux.zsh-syntax \
+  .#checks.x86_64-linux.bash-syntax
+nix eval --raw '.#nixosConfigurations.nixos-wsl.config.system.build.toplevel.drvPath'
+```
+
+Nix quality runs nixfmt, statix, and deadnix on Nix files. Lua formatting uses
+StyLua for Neovim and WezTerm. Shell checks parse the Bash and Zsh startup
+files. CI does not build full NixOS systems, evaluate the native host, install
+Homebrew/pacman packages, or activate Stow links.
+
+`nix develop` provides deadnix, Git, nil, nixfmt, statix, StyLua, Vim, and Zsh.
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index 6af90d4..2ff5ae7 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -1,468 +1,250 @@
-# Deployment Guide for Cross-Platform Dotfiles
+# Deployment Guide
 
-This repository provides reproducible configurations for:
-- **NixOS WSL2** (Windows Subsystem for Linux)
-- **NixOS Native** (bare metal or VM)
-- **Archlinux** with Nix + Home Manager
-- **macOS** with nix-darwin (current setup)
+| Platform | Packages | Dotfiles |
+| --- | --- | --- |
+| macOS | Homebrew Bundle using the root `Brewfile` | GNU Stow |
+| Arch Linux | pacman using the root `pacman-packages.txt` | GNU Stow |
+| NixOS WSL2 | Nix flake, `nixos-wsl` | Integrated Home Manager |
+| Native NixOS | Nix flake, `nixos-native` | Integrated Home Manager |
 
-## Directory Structure
+Nix is not required or configured for macOS or Arch Linux. The native package
+lists do not mirror the larger NixOS package set.
 
-```
-dotfiles/
-├── flake.nix                  # Main flake configuration
-├── home/                      # Home Manager configurations
-│   ├── modules/              # Shared modules
-│   │   ├── common.nix        # Common settings
-│   │   ├── shell.nix         # Shell configuration
-│   │   ├── dev-tools.nix     # Development tools
-│   │   ├── neovim.nix        # Neovim configuration
-│   │   └── terminal.nix      # Terminal multiplexers & emulators
-│   ├── nixos-wsl.nix         # WSL2-specific home config
-│   ├── nixos-native.nix      # Native NixOS home config
-│   ├── archlinux.nix         # Archlinux home config
-│   └── darwin.nix            # macOS home config
-├── systems/                   # NixOS system configurations
-│   ├── wsl/
-│   │   └── configuration.nix # WSL2 system config
-│   ├── native/
-│   │   └── configuration.nix # Native NixOS system config
-│   └── darwin/
-│       └── configuration.nix # macOS system config
-└── [app-configs]/            # Existing dotfiles (nvim, herdr, wezterm, etc.)
-```
-
-## Prerequisites
-
-All platforms need Nix with flakes enabled. Choose your platform:
-
-### For NixOS (WSL2 or Native)
-Nix is already installed. Ensure flakes are enabled in `/etc/nixos/configuration.nix`:
-```nix
-nix.settings.experimental-features = [ "nix-command" "flakes" ];
-```
-
-### For Archlinux or other Linux distributions
-```bash
-# Install Nix using Determinate Systems installer (recommended)
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-
-# Or use official installer
-sh <(curl -L https://nixos.org/nix/install) --daemon
-```
-
-### For macOS
-```bash
-# Install Nix (if not already installed)
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-```
-
-## Bootstrap Process (First-Time Setup on Clean NixOS)
+## Before installing
 
-**The Chicken-and-Egg Problem**: On a fresh NixOS installation (WSL2 or Native), git is not installed by default, but you need git to clone the dotfiles repository. Here's how to solve this:
+Review the configuration before using it on another machine. Back up individual
+files that would conflict with symlinks; neither Stow nor Home Manager should
+overwrite your existing configuration. Do not use `stow --adopt` unless you
+intend to move existing files into this repository.
 
-### Option 1: Using nix-shell (Traditional Method)
+Keep the checkout at `~/dotfiles`. NixOS explicitly expects
+`/home/user3301/dotfiles`, and the Zsh local override also uses `~/dotfiles`.
+Do not run Stow on paths already managed by Home Manager.
 
-```bash
-# Enter a temporary shell with git
-nix-shell -p git
+For macOS and Arch Linux, start with Git installed and clone the repository:
 
-# Clone the dotfiles repo (while in nix-shell)
+```sh
 git clone https://github.com/user3301/dotfiles.git ~/dotfiles
 cd ~/dotfiles
-
-# Link the NixOS configuration and build
-make setup-wsl-nixos  # for WSL2 (stages config for next boot)
-
-# Exit the temporary shell
-exit
-
-# Then restart WSL (in PowerShell): wsl --shutdown
-# Reopen NixOS and run: cd ~/dotfiles && make switch
-
-# Now git is permanently installed as part of your system!
 ```
 
-### Option 2: Using nix run (Modern Method)
-
-```bash
-# Clone using temporary git (no shell needed)
-nix run nixpkgs#git -- clone https://github.com/user3301/dotfiles.git ~/dotfiles
-cd ~/dotfiles
-
-# Link the NixOS configuration and build
-make setup-wsl-nixos  # for WSL2 (stages config for next boot)
+On macOS, Apple's Command Line Tools provide Git and Make; install them with
+`xcode-select --install` if needed. On Arch Linux, install Git first with
+`sudo pacman -Syu --needed git`. If Make is not yet available, use the direct
+package installation commands below; the Arch list includes `base-devel`.
 
-# Then restart WSL (in PowerShell): wsl --shutdown
-# Reopen NixOS and run: cd ~/dotfiles && make switch
-```
+## macOS
 
-**After the first deployment**, git is permanently installed as part of `environment.systemPackages`, so you can use it normally for updates:
+Install [Homebrew](https://brew.sh/) if necessary (`make install-brew` runs its
+installer). Follow the installer's shell setup instructions so `brew` is on
+`PATH`; the prefix differs between Apple Silicon and Intel.
 
-```bash
+```sh
 cd ~/dotfiles
-git pull
-make switch
+brew bundle --file=Brewfile
 ```
 
----
-
-## Deployment Instructions
-
-After the first Nix build on a new machine, manually install the Herdr plugins [Auto Title](https://github.com/kryptamine/herdr-auto-title) and [reviewr](https://github.com/persiyanov/herdr-reviewr). These two plugins are not managed by Nix.
-
-### 1. NixOS WSL2
+The Brewfile installs GNU Stow, git-delta, Herdr, WezTerm, and AeroSpace. It does
+not install the full NixOS toolchain or manage macOS system preferences.
 
-**First-time setup on clean WSL2:**
+Before enabling the Zsh configuration, read [Shell and application
+dependencies](#shell-and-application-dependencies). Then preview and create links:
 
-```bash
-# Step 1: Get temporary git access (choose one method from Bootstrap Process above)
-nix-shell -p git
-
-# Step 2: Clone the dotfiles repo
-git clone https://github.com/user3301/dotfiles.git ~/dotfiles
-cd ~/dotfiles
-
-# Step 3: Link config, build, and stage the system for next boot
-make setup-wsl-nixos
-
-# Step 4: Exit temporary shell and restart WSL
-exit
-```
-
-Then in **PowerShell / Windows Terminal**:
-```powershell
-wsl --shutdown
+```sh
+stow --simulate --verbose --target="$HOME" \
+  bash fastfetch git herdr lazygit nvim wezterm yazi zsh aerospace
+stow --target="$HOME" \
+  bash fastfetch git herdr lazygit nvim wezterm yazi zsh aerospace
 ```
 
-Reopen your NixOS WSL2 distro:
-```bash
-# Step 5: Verify the configuration is active
-cd ~/dotfiles
-make switch
-```
+`make setup-mac` runs the Brewfile installation and Stow steps in order. It
+requires Homebrew to be installed already and does not change your login shell.
+On later updates, rerun `brew bundle --file=Brewfile` for manifest changes and
+Stow when adding config files or packages.
 
-> **Why `boot` then restart?** NixOS 25.05+ changed the default D-Bus
-> implementation from `dbus` to `dbus-broker`. A live `switch` on a fresh
-> install triggers a switch inhibitor for this critical component change.
-> Using `boot` stages the config cleanly, and the WSL restart activates it.
+## Arch Linux
 
-The system will have:
-- Configured WSL2 settings
-- Created user `user3301`
-- Installed Home Manager packages
-- Symlinked all dotfiles
-- Permanently installed git and other system packages
+Install the root package list using a full system upgrade, avoiding partial
+upgrades:
 
-**Subsequent updates:**
-```bash
+```sh
 cd ~/dotfiles
-make switch
+sudo pacman -Syu --needed - < pacman-packages.txt
 ```
 
-**Important Notes for WSL2:**
-- Username is `user3301` (configured in `systems/wsl/configuration.nix`)
-- Default shell is zsh
-- WSL interoperability is enabled by default
-- Windows paths are accessible via `/mnt/c/...`
-
-### 2. NixOS Native
-
-**First-time setup on clean NixOS:**
-
-```bash
-# Step 1: Get temporary git access (see Bootstrap Process above)
-nix-shell -p git
-
-# Step 2: Clone the dotfiles repo
-git clone https://github.com/user3301/dotfiles.git ~/dotfiles
-cd ~/dotfiles
-
-# Step 3: IMPORTANT - Generate hardware configuration first
-sudo nixos-generate-config --show-hardware-config > ~/dotfiles/systems/native/hardware-configuration.nix
-
-# Step 4: Edit systems/native/configuration.nix to uncomment the hardware import:
-# imports = [ ./hardware-configuration.nix ];
-
-# Step 5: Customize your setup in systems/native/configuration.nix:
-#   - Choose display manager, desktop environment
-#   - Configure graphics drivers
-#   - Set hostname, timezone, locale
-
-# Step 6: Deploy the system configuration
-sudo nixos-rebuild switch --flake .#nixos-native
+The list includes Git, OpenSSH, Stow, Zsh, eza, Lazygit, fd, ripgrep, GitHub CLI,
+xclip, `base-devel`, sudo, and which. It does not include every configured
+application: for example, Neovim and delta need to be installed separately if
+you use the editor and Git configurations.
 
-# Step 7: Exit temporary shell
-exit
-```
+After preparing the dependencies below, link the desired packages:
 
-**Subsequent updates:**
-```bash
-cd ~/dotfiles
-sudo nixos-rebuild switch --flake .#nixos-native
+```sh
+stow --simulate --verbose --target="$HOME" \
+  bash fastfetch git herdr lazygit nvim wezterm yazi zsh
+stow --target="$HOME" \
+  bash fastfetch git herdr lazygit nvim wezterm yazi zsh
 ```
 
-**Customization:**
-Before deploying, edit `systems/native/configuration.nix` to:
-- Choose display manager (lightdm, gdm, etc.)
-- Choose desktop environment (GNOME, KDE, i3, etc.)
-- Configure graphics drivers (NVIDIA, AMD, Intel)
-- Set timezone and locale
-- Configure networking hostname
-
-### 3. Archlinux with Nix + Home Manager
-
-**First-time setup:**
+With Make available, `make setup-arch` installs the pacman list and then creates
+these links. AeroSpace is macOS-only and is not included.
 
-```bash
-# 1. Install Nix (if not already done)
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
+## Shell and application dependencies
 
-# 2. Clone dotfiles
-git clone https://github.com/yourusername/dotfiles.git ~/dotfiles
-cd ~/dotfiles
-
-# 3. Edit home/archlinux.nix to set your actual username
-# Change 'user3301' to your actual Arch username
-
-# 4. Deploy Home Manager configuration
-nix run home-manager/master -- switch --flake .#user@linux
+Stow only creates links; it does not install applications or their dependencies.
+Add desired macOS packages to `Brewfile`, or Arch packages to
+`pacman-packages.txt`, and rerun the corresponding install command.
 
-# Note: Replace 'user@linux' with 'username@linux' if you changed the username
-```
+The shared Zsh config unconditionally loads Oh My Zsh from `~/.oh-my-zsh`.
+On macOS and Arch Linux, install it before opening a shell with this config.
+If that directory does not already exist:
 
-**Subsequent updates:**
-```bash
-cd ~/dotfiles
-home-manager switch --flake .#user@linux
+```sh
+git clone https://github.com/ohmyzsh/ohmyzsh.git ~/.oh-my-zsh
 ```
 
-**Important Notes for Archlinux:**
-- This is a **standalone Home Manager** setup (no NixOS)
-- System packages should still be installed via `pacman`
-- Nix manages development tools and user applications
-- Username must match your actual Arch username
-- Edit `home/archlinux.nix` to set correct username and home directory
-
-### 4. macOS (Current Setup)
+Zsh uses the `pygmalion` theme and the Git, z, colored-man-pages, asdf, and vi-mode
+plugins. Its `ls` aliases require eza. Both shells select `nvim` as the editor,
+so install Neovim or adjust the editor setting. McFly is optional; Bash also
+uses zoxide when installed. The asdf plugin/shim path does not install asdf or
+any language runtimes.
 
-**First-time setup:**
+Git and Lazygit use delta. Configure your Git identity and signing key using
+the [Git README](../git/.config/git/README.md). Language-server and formatter
+dependencies are covered in the [Neovim README](../nvim/.config/nvim/README.md).
+WezTerm's font configuration requests JetBrains Mono, Ubuntu Mono, and More
+Perfect DOS VGA; install desired fonts separately on non-NixOS machines.
 
-```bash
-# Already set up via nix-darwin
-# Use existing Makefile commands:
-make setup-mac
-```
+The default `make stow` selection is:
+`bash fastfetch git herdr lazygit nvim wezterm yazi zsh`.
+You can link a smaller subset:
 
-**Subsequent updates:**
-```bash
-darwin-rebuild switch --flake .#aarch64  # For Apple Silicon
-# or
-darwin-rebuild switch --flake .#x86_64   # For Intel Macs
+```sh
+make stow STOW_PACKAGES="git nvim"
 ```
 
-## Configuration Customization
+`make setup-mac` adds `aerospace` to that selection. `vim` is another Stow
+package, but it is not linked by default: its file is `~/.config/vim/vimrc`.
+If your Vim does not discover that path, load it explicitly with
+`vim -u ~/.config/vim/vimrc` or source it from your own `~/.vimrc`.
 
-### Changing Username or Email
+After installing Zsh, `make set-default-shell` registers it in `/etc/shells`
+if needed and calls `chsh`. Log out and back in afterward.
 
-Edit the appropriate home configuration file:
-- **WSL2**: `home/nixos-wsl.nix`
-- **Native NixOS**: `home/nixos-native.nix`
-- **Archlinux**: `home/archlinux.nix`
-- **macOS**: `home/darwin.nix`
+### Migrating an existing Nix-managed macOS or Arch home
 
-```nix
-programs.git = {
-  enable = true;
-  userName = "Your Name";
-  userEmail = "your.email@example.com";
-};
-```
+Removing this repository's old Nix configuration does not uninstall Nix or
+remove links from a previously activated generation. Back up local overrides,
+install native replacements, and retire the previous Home Manager/nix-darwin
+setup using the tooling that created it before Stowing the same paths. Check
+existing links with `ls -l`; do not let Stow write through an old Nix-managed
+directory. NixOS homes should continue using Home Manager instead.
 
-### Adding New Packages
+## NixOS WSL2
 
-**System-wide packages (NixOS only):**
-Edit `systems/{wsl,native}/configuration.nix`:
-```nix
-environment.systemPackages = with pkgs; [
-  vim
-  git
-  # Add your packages here
-];
-```
+Start with an existing [NixOS-WSL](https://github.com/nix-community/NixOS-WSL)
+distribution, not Ubuntu or another WSL distribution. From a user able to run
+sudo:
 
-**User packages (all platforms):**
-Edit `home/modules/dev-tools.nix` or your platform-specific home config:
-```nix
-home.packages = with pkgs; [
-  # Add your packages here
-  htop
-  docker
-];
+```sh
+nix --extra-experimental-features 'nix-command flakes' run github:user3301/dotfiles#bootstrap-wsl
 ```
 
-### Adding New Modules
+The app in `scripts/bootstrap-nixos-wsl.sh` checks for WSL and `nixos-rebuild`,
+then switches to `nixos-wsl-bootstrap`. That configuration creates `user3301`
+and clones the repository to `/home/user3301/dotfiles` before Home Manager
+activation. An existing Git checkout is left intact; an existing non-checkout
+at that path is rejected. It can be rerun after an interrupted bootstrap.
+`DOTFILES_FLAKE` overrides the rebuild's flake reference, not the clone URL.
 
-Create a new module in `home/modules/` and import it in your platform configs:
+From PowerShell, restart WSL:
 
-```nix
-# home/modules/mymodule.nix
-{ config, pkgs, lib, ... }:
-{
-  # Your module configuration
-}
-
-# Then import in home/nixos-wsl.nix (or other configs)
-imports = [
-  ./modules/common.nix
-  ./modules/mymodule.nix  # Add this
-];
+```powershell
+wsl --shutdown
 ```
 
-## Updating Flake Inputs
+Reopen as `user3301`, then use the normal output for subsequent changes:
 
-```bash
-# Update all inputs
-nix flake update
-
-# Update specific input
-nix flake lock --update-input nixpkgs
-
-# Then rebuild your system
-sudo nixos-rebuild switch --flake .#nixos-wsl  # or your config
+```sh
+cd ~/dotfiles
+make switch
 ```
 
-## Troubleshooting
-
-### Symlinks not working on Archlinux
+The WSL configuration enables Zsh, Docker, Windows interoperability, and
+`nix-ld`; the SSH server is disabled. WezTerm is not installed or linked by this
+home configuration: the terminal runs on the Windows host and must be configured
+there separately.
 
-On non-NixOS systems, Home Manager uses `mkOutOfStoreSymlink` which requires absolute paths. Ensure `config.home.homeDirectory` is set correctly in `home/archlinux.nix`.
+For an existing checkout at the expected user path, `make setup-wsl-nixos` is
+the alternate boot-staging workflow. It links the WSL system module into
+`/etc/nixos/configuration.nix` and runs `nixos-rebuild boot --flake .#nixos-wsl`.
+Restart WSL afterward. Continue using explicit `--flake` commands: that module
+alone is not the full configuration.
 
-### "conflicting files" error
+## Native NixOS
 
-Home Manager won't overwrite existing files. Either:
-1. Backup and remove conflicting files: `mv ~/.config/nvim ~/.config/nvim.bak`
-2. Or let Home Manager manage the files by using `home.file."path".force = true`
+This is a configuration for an already installed x86_64 NixOS system, not a disk
+installer. It currently imports `systems/hardware/hardware-vb.nix`, which
+contains VirtualBox-specific modules and filesystem UUIDs. **Replace that
+hardware import before deploying to another machine.**
 
-### WSL2 specific issues
+If Git is unavailable, obtain it temporarily with `nix-shell -p git`. Clone as
+the intended user into `/home/user3301/dotfiles`, then:
 
-**Permission denied on /etc/nixos:**
-```bash
-sudo mkdir -p /etc/nixos
-sudo chown -R $USER:$USER /etc/nixos
-```
-
-**Windows paths not accessible:**
-Ensure WSL interop is enabled in `systems/wsl/configuration.nix`:
-```nix
-wsl.interop.register = true;
+```sh
+cd ~/dotfiles
+sudo nixos-generate-config --show-hardware-config > systems/native/hardware-configuration.nix
 ```
 
-### Flake evaluation errors
-
-```bash
-# Check for syntax errors
-nix flake check
+Change the `imports` entry in `systems/native/configuration.nix` from
+`../hardware/hardware-vb.nix` to `./hardware-configuration.nix`. Add the new file
+to Git so the local Git-backed flake can see it:
 
-# Show detailed evaluation
-nix flake show --allow-import-from-derivation
+```sh
+git add systems/native/hardware-configuration.nix
 ```
 
-## Migration Strategy
-
-### From existing non-Nix setup
-
-1. **Backup existing configs**:
-   ```bash
-   mv ~/.config ~/.config.backup
-   ```
-
-2. **Deploy minimal configuration first**:
-   Comment out modules in your home config and add them incrementally
-
-3. **Test each module**:
-   After adding each module, rebuild and verify it works
-
-4. **Keep both systems during transition**:
-   You can keep your old configs and gradually migrate
-
-### From NixOS without flakes
-
-1. **Enable flakes** in your current `/etc/nixos/configuration.nix`:
-   ```nix
-   nix.settings.experimental-features = [ "nix-command" "flakes" ];
-   ```
-
-2. **Rebuild to enable flakes**:
-   ```bash
-   sudo nixos-rebuild switch
-   ```
-
-3. **Then switch to flake configuration**:
-   ```bash
-   cd ~/dotfiles
-   sudo nixos-rebuild switch --flake .#nixos-wsl
-   ```
+Review bootloader, user, hostname, networking, and graphics settings. The
+current desktop uses X11, Qtile, and LightDM; NetworkManager and the SSH server
+are enabled, with password and root SSH login disabled.
 
-## Platform-Specific Notes
-
-### NixOS WSL2
-- **Pros**: Full NixOS experience, declarative system config
-- **Cons**: WSL2 limitations (no systemd by default, handled by nixos-wsl)
-- **Use case**: Development environment on Windows
-
-### NixOS Native
-- **Pros**: Full system control, best Nix experience
-- **Cons**: Learning curve, need to configure hardware
-- **Use case**: Primary workstation, servers
-
-### Archlinux + Nix/Home Manager
-- **Pros**: Best of both worlds (pacman + Nix), gradual adoption
-- **Cons**: Two package managers, can't configure system via Nix
-- **Use case**: Already on Arch, want reproducible user environment
-
-### macOS + nix-darwin
-- **Pros**: Declarative package management on macOS
-- **Cons**: Still need Homebrew for some GUI apps, macOS updates can break Nix
-- **Use case**: Development on macOS
-
-## Advanced Usage
-
-### Testing configurations without switching
-
-```bash
-# NixOS
-sudo nixos-rebuild test --flake .#nixos-wsl
-
-# Home Manager
-home-manager build --flake .#user@linux
-./result/activate
+```sh
+sudo nixos-rebuild build --flake .#nixos-native
+sudo nixos-rebuild switch --flake .#nixos-native
 ```
 
-### Building for different architecture
+If flakes are not enabled yet, pass the setting to the rebuild explicitly:
 
-```bash
-# Build for ARM64 from x86_64
-nix build .#homeConfigurations.user@linux-arm64.activationPackage \
-  --system aarch64-linux
+```sh
+sudo env NIX_CONFIG='experimental-features = nix-command flakes' \
+  nixos-rebuild build --flake .#nixos-native
 ```
 
-### Using direnv (optional)
+Use the same prefix for `switch`. The deployed configuration enables flakes
+permanently.
 
-Create `.envrc` in project directories:
-```bash
-use flake
-```
+Both NixOS outputs hard-code `user3301`. To change it, update the system user,
+the matching `home-manager.users` key in `flake.nix`, and `home.username` and
+`home.homeDirectory` in the selected home module. WSL bootstrap additionally
+hard-codes its user and clone location in the flake and bootstrap script.
+
+## Local settings and manual steps
 
-Then `direnv allow` to auto-load Nix environments.
+The following local overrides are already ignored by Git:
 
-## Support
+| File | Loaded by |
+| --- | --- |
+| `git/.config/git/config.local` | Shared Git config, after the defaults |
+| `zsh/.zshenv.local` | `~/.zshenv`, from `~/dotfiles` |
+| `bash/.bashrc.local` | Interactive Bash, from `$DOTFILES/bash` |
 
-For issues or questions:
-1. Check the NixOS Wiki: https://nixos.wiki/
-2. NixOS Discourse: https://discourse.nixos.org/
-3. Home Manager Manual: https://nix-community.github.io/home-manager/
+Do not commit credentials or private keys. There is no automated secrets
+provisioning.
 
----
+Install Herdr's [Auto Title](https://github.com/kryptamine/herdr-auto-title) and
+[reviewr](https://github.com/persiyanov/herdr-reviewr) plugins manually when using
+Herdr. The tracked config binds `Alt+r` to reviewr; plugin state is ignored.
+Herdr and Fastfetch auto-start snippets in `.zshrc` are commented out.
 
-**Remember**: The beauty of this setup is reproducibility. Once configured, you can deploy identical environments across all your machines with a single command!
+See [NixOS maintenance](README.nix.md) and the
+[command reference](QUICK_REFERENCE.md) for updates and troubleshooting.
diff --git a/docs/EXAMPLE-VERSION-PINNING.md b/docs/EXAMPLE-VERSION-PINNING.md
index e4ce5ff..20da74c 100644
--- a/docs/EXAMPLE-VERSION-PINNING.md
+++ b/docs/EXAMPLE-VERSION-PINNING.md
@@ -1,269 +1,100 @@
-# How to Pin Specific Package Versions in Nix
+# Nix Package Version Pinning
 
-This guide shows how to use different versions of packages from different nixpkgs commits.
+This guide describes the overrides in `flake.nix`. They apply to NixOS only;
+macOS and Arch Linux packages come from `Brewfile` and `pacman-packages.txt`.
 
-## Scenario
+## Main package set
 
-You want:
-- **Package A** (e.g., neovim 0.11.5) from nixpkgs commit `abc123`
-- **Package B** (e.g., ripgrep 14.0.0) from nixpkgs commit `def456`
-- **Everything else** from the latest unstable
+`nixpkgs` tracks `nixos-26.05` and Home Manager tracks `release-26.05`.
+`flake.lock` pins their resolved commits. Updates are explicit:
 
-## Step 1: Find the Right Commits
-
-### Method 1: Using nixpkgs commit history
-
-1. Go to https://github.com/NixOS/nixpkgs/commits/master
-2. Search for commits that updated your package
-3. Or use GitHub search: `repo:NixOS/nixpkgs neovim 0.11.5`
-
-### Method 2: Using search.nixos.org
-
-1. Visit https://search.nixos.org/packages
-2. Search for your package (e.g., "neovim")
-3. Select different channels/versions to see what's available
-4. Note the channel name (e.g., `nixos-24.05`, `nixpkgs-unstable`)
-
-### Method 3: Using Nix CLI to check versions
-
-```bash
-# Check version in current unstable
-nix eval nixpkgs#neovim.version
-
-# Check version at a specific commit
-nix eval github:NixOS/nixpkgs/abc123def456#neovim.version
-
-# Search for a package
-nix search nixpkgs#neovim
+```sh
+nix flake update nixpkgs home-manager
 ```
 
-## Step 2: Update flake.nix
-
-Add additional nixpkgs inputs for each version you need:
-
-```nix
-{
-  description = "Gaiz's dotfiles - Nix flake configuration";
-
-  inputs = {
-    # Main nixpkgs (latest unstable)
-    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
-
-    # Pinned version for Package A (neovim 0.11.5)
-    # Replace 'abc123def456' with actual commit hash
-    nixpkgs-neovim.url = "github:NixOS/nixpkgs/abc123def456";
-
-    # Pinned version for Package B (ripgrep 14.0.0)
-    # Replace 'def789ghi012' with actual commit hash
-    nixpkgs-ripgrep.url = "github:NixOS/nixpkgs/def789ghi012";
-
-    # You can also use branch names or tags
-    nixpkgs-stable.url = "github:NixOS/nixpkgs/nixos-24.11";
-
-    nix-darwin = {
-      url = "github:LnL7/nix-darwin";
-      inputs.nixpkgs.follows = "nixpkgs";
-    };
-
-    home-manager = {
-      url = "github:nix-community/home-manager";
-      inputs.nixpkgs.follows = "nixpkgs";
-    };
-  };
-
-  outputs = { self, nixpkgs, nixpkgs-neovim, nixpkgs-ripgrep, nix-darwin, home-manager, ... }:
-    let
-      username = builtins.getEnv "USER";
-
-      # Helper to create package sets for different nixpkgs
-      mkPkgs = system: nixpkgsInput: import nixpkgsInput {
-        inherit system;
-        config.allowUnfree = true;
-      };
+This updates the lockfile, not the running system. Rebuild the selected NixOS
+configuration afterward.
 
-      mkSystem = system:
-        let
-          pkgs = mkPkgs system nixpkgs;
-          pkgs-neovim = mkPkgs system nixpkgs-neovim;
-          pkgs-ripgrep = mkPkgs system nixpkgs-ripgrep;
-        in
-        nix-darwin.lib.darwinSystem {
-          inherit system;
-          modules = [
-            home-manager.darwinModules.home-manager
-            {
-              nix.settings.experimental-features = "nix-command flakes";
-              system.stateVersion = 5;
+## Azure CLI: a separate nixpkgs revision
 
-              home-manager.useGlobalPkgs = true;
-              home-manager.useUserPackages = true;
-              home-manager.users.${username} = import ./home.nix;
-
-              # Pass the custom package sets to home-manager
-              home-manager.extraSpecialArgs = {
-                inherit pkgs-neovim pkgs-ripgrep;
-              };
-            }
-          ];
-        };
-
-      mkHome = system:
-        let
-          pkgs = mkPkgs system nixpkgs;
-          pkgs-neovim = mkPkgs system nixpkgs-neovim;
-          pkgs-ripgrep = mkPkgs system nixpkgs-ripgrep;
-        in
-        home-manager.lib.homeManagerConfiguration {
-          inherit pkgs;
-          modules = [
-            ./home.nix
-          ];
-          # Pass the custom package sets to home.nix
-          extraSpecialArgs = {
-            inherit pkgs-neovim pkgs-ripgrep;
-          };
-        };
-    in
-    {
-      darwinConfigurations = {
-        "aarch64" = mkSystem "aarch64-darwin";
-        "x86_64" = mkSystem "x86_64-darwin";
-      };
-
-      homeConfigurations = {
-        "${username}-aarch64" = mkHome "aarch64-darwin";
-        "${username}-x86_64" = mkHome "x86_64-darwin";
-      };
-    };
-}
-```
-
-## Step 3: Update home.nix
-
-Use the pinned packages in your home configuration:
+The flake pins `nixpkgs-azure-cli` to
+`286615174c6bd765907ef9975d0acdc799c7bf7e`, which provides Azure CLI 2.77.0.
+It does not follow the main nixpkgs input. The overlay imports that package set
+for the host system and exposes its Azure CLI:
 
 ```nix
-{ config, pkgs, lib, pkgs-neovim ? pkgs, pkgs-ripgrep ? pkgs, ... }:
-
-let
-  username = builtins.getEnv "USER";
-in
-{
-  home.username = username;
-  home.homeDirectory = lib.mkDefault "/Users/${username}";
-  home.stateVersion = "24.11";
-
-  programs.home-manager.enable = true;
-
-  home.packages = [
-    # Use default nixpkgs
-    pkgs.git
-    pkgs.fzf
-    pkgs.bat
-
-    # Use pinned neovim from specific commit
-    pkgs-neovim.neovim
-
-    # Use pinned ripgrep from specific commit
-    pkgs-ripgrep.ripgrep
-  ];
-}
+azureCliOverlay = final: _prev: {
+  inherit (import inputs.nixpkgs-azure-cli { inherit (final.stdenv.hostPlatform) system; })
+    azure-cli
+    ;
+};
 ```
 
-## Step 4: Lock and Build
-
-```bash
-# Generate/update flake.lock
-nix flake lock
+`mkSystem` installs the overlay in `nixpkgs.overlays`. Because integrated Home
+Manager uses the global package set, `pkgs.azure-cli` in
+`home/modules/dev-tools.nix` resolves to the pinned version.
 
-# Check what versions you'll get
-nix eval .#homeConfigurations.${USER}-aarch64.config.home.packages.0.version
+Inspect the actual package selected by the system:
 
-# Build and activate
-darwin-rebuild switch --flake .#aarch64
-# OR
-home-manager switch --flake .#$USER-aarch64
+```sh
+nix eval --raw '.#nixosConfigurations.nixos-wsl.pkgs.azure-cli.version'
 ```
 
-## Alternative: Using Overlays (Advanced)
+To change it, choose a nixpkgs commit containing the desired package, change
+the input URL, and run `nix flake lock`. Updating other inputs does not move
+this explicit commit pin.
 
-If you prefer, you can use overlays to override package versions:
+## Copilot CLI: version and source override
 
-```nix
-# In home.nix
-{ config, pkgs, lib, ... }:
+`copilotOverlay` overrides the existing `github-copilot-cli` derivation's
+version and source. It currently selects 1.0.70 and platform-specific
+`linux-x64` / `linux-arm64` release archives, each with its own hash, while
+retaining the nixpkgs packaging logic.
 
-{
-  nixpkgs.overlays = [
-    # Override neovim to a specific version
-    (final: prev: {
-      neovim = prev.neovim.overrideAttrs (oldAttrs: rec {
-        version = "0.11.5";
-        src = prev.fetchFromGitHub {
-          owner = "neovim";
-          repo = "neovim";
-          rev = "v${version}";
-          hash = "sha256-..."; # Use nix-prefetch-url to get this
-        };
-      });
-    })
-  ];
-
-  home.packages = with pkgs; [
-    neovim  # Will use overridden version
-    git
-  ];
-}
+```sh
+nix eval --raw '.#nixosConfigurations.nixos-wsl.pkgs.github-copilot-cli.version'
 ```
 
-## Finding Commit Hashes
-
-### Quick method using Nix:
+When changing this override, update both the version and each supported
+platform's archive hash in `flake.nix`. A version edit without matching hashes
+is insufficient. Build the package before deploying:
 
-```bash
-# Find commits for a specific package version
-nix-locate --at-root --top-level --whole-name "bin/nvim" | grep "neovim-0.11"
-
-# Or check nixpkgs history
-git clone https://github.com/NixOS/nixpkgs --depth 1000
-cd nixpkgs
-git log --all --grep="neovim.*0.11.5" --oneline
+```sh
+nix build --no-link '.#nixosConfigurations.nixos-wsl.pkgs.github-copilot-cli'
 ```
 
-### Using nixpkgs-review:
+The flake comment links the upstream nixpkgs issue motivating this workaround.
+Remove the overlay when the pinned main package set supplies the desired
+working package.
 
-```bash
-# Search nixpkgs history
-nix run nixpkgs#gh -- search commits --repo=NixOS/nixpkgs "neovim 0.11.5"
-```
+## Claude Code and Herdr
 
-## Summary
+Claude Code comes from `claude-code-nix.overlays.default`. Herdr is installed
+directly from `inputs.herdr.packages.<system>.default` in `terminal.nix`.
+Both inputs follow the main nixpkgs package set and have their own revisions
+recorded in `flake.lock`.
 
-**For multiple package versions:**
+```sh
+nix flake update claude-code-nix herdr
+```
 
-1. Add each nixpkgs input with desired commit/branch:
-   ```nix
-   nixpkgs-packageA.url = "github:NixOS/nixpkgs/<commit>";
-   nixpkgs-packageB.url = "github:NixOS/nixpkgs/<commit>";
-   ```
+## Adding another pin
 
-2. Create package sets for each:
-   ```nix
-   pkgs-packageA = mkPkgs system nixpkgs-packageA;
-   ```
+Prefer the existing pattern: add a commit-pinned input when you need the
+package and its dependency set from that revision, then add a narrowly scoped
+overlay to `mkSystem`. For a source-only override, review whether the current
+nixpkgs patches, dependencies, and build steps still apply to the new source.
+Do not merely change `version` and assume the package source changed with it.
 
-3. Pass them to home.nix:
-   ```nix
-   extraSpecialArgs = { inherit pkgs-packageA pkgs-packageB; };
-   ```
+Keep overrides at the system package-set level so both NixOS and integrated
+Home Manager see the same package. Review the lockfile diff to avoid unrelated
+upgrades.
 
-4. Use in home.nix:
-   ```nix
-   { pkgs, pkgs-packageA, pkgs-packageB, ... }:
-   home.packages = [
-     pkgs-packageA.packageA
-     pkgs-packageB.packageB
-   ];
-   ```
+```sh
+nix flake check
+sudo nixos-rebuild build --flake .#nixos-wsl
+sudo nixos-rebuild switch --flake .#nixos-wsl
+```
 
-This gives you complete control over each package's version!
+Use `.#nixos-native` for the native host. Commit deliberate flake and lockfile
+changes together.
diff --git a/docs/IMPLEMENTATION_SUMMARY.md b/docs/IMPLEMENTATION_SUMMARY.md
index a445dcd..209baf8 100644
--- a/docs/IMPLEMENTATION_SUMMARY.md
+++ b/docs/IMPLEMENTATION_SUMMARY.md
@@ -1,466 +1,41 @@
-# Implementation Summary
-
-## What Was Created
-
-A complete Nix flakes-based dotfiles architecture supporting three target platforms with maximum code reuse and reproducibility.
-
-## File Structure Created
-
-### Core Configuration Files
-
-```
-flake.nix                           # Main entry point, defines all outputs
-├── NixOS configurations (nixosConfigurations)
-│   ├── nixos-wsl                  # WSL2 system + home
-│   └── nixos-native               # Native NixOS system + home
-├── Home Manager configurations (homeConfigurations)
-│   ├── user@linux                 # Standalone for Archlinux (x86_64)
-│   └── user@linux-arm64           # Standalone for Archlinux (ARM)
-└── Darwin configurations (darwinConfigurations)
-    ├── aarch64                    # macOS Apple Silicon
-    └── x86_64                     # macOS Intel
-```
-
-### System Configurations (NixOS only)
-
-```
-systems/
-├── wsl/configuration.nix          # WSL2-specific system settings
-├── native/configuration.nix       # Native NixOS system settings
-└── darwin/configuration.nix       # macOS system settings (nix-darwin)
-```
-
-**Key Features**:
-- User account creation (`user3301`)
-- Nix flakes enabled
-- Automatic garbage collection
-- Minimal system packages (most go in Home Manager)
-- Platform-specific settings (WSL interop, desktop environment, macOS defaults)
-
-### Home Manager Configurations
-
-```
-home/
-├── nixos-wsl.nix                  # WSL2 user configuration
-├── nixos-native.nix               # Native NixOS user configuration
-├── archlinux.nix                  # Archlinux user configuration
-└── darwin.nix                     # macOS user configuration
-```
-
-**Key Features**:
-- Imports shared modules
-- Sets username and home directory
-- Platform-specific packages
-- Git user configuration
-
-### Shared Modules (Reusable Components)
-
-```
-home/modules/
-├── common.nix                     # Base configuration for all platforms
-├── shell.nix                      # Zsh with plugins
-├── dev-tools.nix                  # Development packages and tools
-├── neovim.nix                     # Neovim with LSPs and formatters
-└── terminal.nix                   # Herdr, Wezterm, Yazi
-```
-
-**Module Responsibilities**:
-
-| Module | Purpose | Packages |
-|--------|---------|----------|
-| common.nix | Base settings | Home Manager self-management, XDG, session vars |
-| shell.nix | Shell config | Zsh with completion, syntax highlighting |
-| dev-tools.nix | Dev tools | git, gh, lazygit, ripgrep, fd, bat, fzf, nil |
-| neovim.nix | Neovim setup | LSPs (lua, nix, ts, python, rust, go), formatters |
-| terminal.nix | Terminal apps | Herdr, Wezterm, Yazi |
-
-### Documentation
-
-```
-DEPLOYMENT.md                      # Detailed deployment guide (all platforms)
-ARCHITECTURE.md                    # Architecture design and decisions
-QUICK_REFERENCE.md                 # Command cheat sheet
-README.nix.md                      # User-facing README
-IMPLEMENTATION_SUMMARY.md          # This file
-```
-
-## Architecture Highlights
-
-### 1. Platform Support Matrix
-
-| Feature | NixOS WSL2 | NixOS Native | Archlinux | macOS |
-|---------|------------|--------------|-----------|-------|
-| System Config | Yes | Yes | No | Yes (darwin) |
-| Home Manager | Yes | Yes | Yes | Yes |
-| Deployment Command | `nixos-rebuild` | `nixos-rebuild` | `home-manager` | `darwin-rebuild` |
-| Username | user3301 | user3301 | user3301 (customizable) | gaiz |
-
-### 2. Code Reuse Strategy
-
-```
-All Platforms (100% shared)
-    └── home/modules/* (shell, dev-tools, neovim, terminal, editors)
-        │
-        ├── NixOS WSL2 (system config + home config)
-        ├── NixOS Native (system config + home config)
-        ├── Archlinux (home config only)
-        └── macOS (darwin config + home config)
-```
-
-**Benefits**:
-- **DRY**: Define package lists once, use everywhere
-- **Consistency**: Same tools on all machines
-- **Maintainability**: Update one module, affects all platforms
-- **Flexibility**: Platform-specific overrides when needed
-
-### 3. Dotfiles Integration
-
-Your existing dotfiles are **symlinked**, not copied:
-
-```
-~/dotfiles/nvim/.config/nvim → ~/.config/nvim
-~/dotfiles/herdr/.config/herdr → ~/.config/herdr
-~/dotfiles/wezterm/.config/wezterm → ~/.config/wezterm
-~/dotfiles/yazi/.config/yazi → ~/.config/yazi
-```
-
-**Why symlinks?**
-- Edit configs directly (no rebuild needed for config changes)
-- Preserve git history
-- Compatible with manual management
-- Works with GNU Stow if needed
-
-### 4. Deployment Workflows
-
-#### NixOS WSL2
-```bash
-cd ~/dotfiles
-sudo nixos-rebuild switch --flake .#nixos-wsl
-```
-**What happens**:
-1. System configuration applied (user, WSL settings)
-2. Home Manager packages installed
-3. Dotfiles symlinked
-4. Shell configured
-
-#### Archlinux
-```bash
-cd ~/dotfiles
-home-manager switch --flake .#user@linux
-```
-**What happens**:
-1. Nix packages installed to user profile
-2. Dotfiles symlinked
-3. Shell configured
-4. System packages (pacman) untouched
-
-### 5. Module Dependencies
-
-```
-common.nix (no dependencies)
-    │
-    ├── shell.nix (uses common.home.homeDirectory)
-    │
-    ├── dev-tools.nix (standalone)
-    │       │
-    │       └── Provides tools for other modules
-    │
-    ├── neovim.nix (uses dev-tools packages)
-    │       │
-    │       └── Symlinks existing nvim config
-    │
-    └── terminal.nix (standalone)
-            │
-            └── Symlinks existing terminal configs
-```
-
-## Key Design Decisions
-
-### 1. Why Flakes?
-- **Reproducibility**: Exact version pinning via flake.lock
-- **Composability**: Easy to combine inputs
-- **Portability**: Self-contained, no channel state
-- **Modern**: Official Nix direction
-
-### 2. Why Separate System and Home Configs?
-- **Portability**: Same user config works on NixOS and non-NixOS
-- **Rollback**: Home Manager changes don't require system reboot
-- **Separation**: Clear boundary between system and user concerns
-
-### 3. Why Symlinks Instead of Copying?
-- **Live editing**: Change configs without rebuilding
-- **Git integration**: Configs stay in version control
-- **Familiarity**: Edit in expected locations
-- **Performance**: No copying large configs
-
-### 4. Why Minimal System Packages?
-- **Portability**: Same packages work on all platforms
-- **Rollback**: Faster home-manager rollbacks
-- **Separation**: System services in system config, everything else in home
-
-### 5. Why Multiple Home Configs Instead of One?
-- **Clarity**: Each platform's config is explicit
-- **Flexibility**: Easy platform-specific overrides
-- **Maintainability**: No complex conditionals in shared code
-
-## Configuration Splitting Strategy
-
-### System Level (NixOS only)
-**Location**: `systems/{wsl,native}/configuration.nix`
-
-**Includes**:
-- Boot configuration
-- User account creation
-- System services (SSH, networking)
-- Hardware configuration
-- Desktop environment (native only)
-- WSL settings (WSL only)
-
-**Excludes**:
-- User packages (except minimal system tools)
-- Dotfiles
-- User-specific settings
-
-### User Level (All Platforms)
-**Location**: `home/{platform}.nix` + `home/modules/*`
-
-**Includes**:
-- All user packages
-- Dotfiles symlinks
-- Shell configuration
-- Git configuration
-- Application settings
-
-**Excludes**:
-- System services
-- Boot configuration
-- User account management
-
-## Deployment Instructions by Platform
-
-### Initial Setup
-
-#### NixOS WSL2
-```bash
-git clone <repo> ~/dotfiles
-cd ~/dotfiles
-sudo nixos-rebuild switch --flake .#nixos-wsl
-```
-
-#### NixOS Native
-```bash
-git clone <repo> ~/dotfiles
-cd ~/dotfiles
-sudo nixos-generate-config --show-hardware-config > systems/native/hardware-configuration.nix
-# Edit systems/native/configuration.nix to uncomment hardware import
-# Customize desktop environment, graphics drivers
-sudo nixos-rebuild switch --flake .#nixos-native
-```
-
-#### Archlinux
-```bash
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-git clone <repo> ~/dotfiles
-cd ~/dotfiles
-# Edit home/archlinux.nix to set your username
-nix run home-manager/master -- switch --flake .#user@linux
-```
-
-### Subsequent Updates
-
-All platforms:
-```bash
-cd ~/dotfiles
-
-# Update flake inputs
-nix flake update
-
-# Apply changes
-sudo nixos-rebuild switch --flake .#nixos-wsl  # NixOS
-home-manager switch --flake .#user@linux       # Archlinux
-```
-
-## Customization Points
-
-### Adding Packages
-
-**System-wide** (NixOS only):
-```nix
-# systems/wsl/configuration.nix
-environment.systemPackages = with pkgs; [
-  mypackage
-];
-```
-
-**User-level** (all platforms):
-```nix
-# home/modules/dev-tools.nix
-home.packages = with pkgs; [
-  mypackage
-];
-```
-
-### Adding Modules
-
-1. Create `home/modules/mymodule.nix`
-2. Import in `home/{platform}.nix`:
-```nix
-imports = [
-  ./modules/common.nix
-  ./modules/mymodule.nix
-];
-```
-
-### Platform-Specific Overrides
-
-```nix
-# home/nixos-wsl.nix
-imports = [ ./modules/common.nix ];
-
-# Override from common
-home.sessionVariables.EDITOR = "vim";  # Instead of nvim
-```
-
-### Conditional Packages
-
-```nix
-# In any module
-home.packages = with pkgs; [
-  universal-package
-] ++ lib.optionals stdenv.isLinux [
-  linux-only-package
-] ++ lib.optionals stdenv.isDarwin [
-  macos-only-package
-];
-```
-
-## Testing Strategy
-
-### Before Deploying
-
-```bash
-# Check syntax
-nix flake check
-
-# Show what's defined
-nix flake show
-
-# Build without activating
-nix build .#nixosConfigurations.nixos-wsl.config.system.build.toplevel
-```
-
-### After Deploying
-
-```bash
-# Test without switching
-sudo nixos-rebuild test --flake .#nixos-wsl
-
-# If good, switch
-sudo nixos-rebuild switch --flake .#nixos-wsl
-
-# If issues, rollback
-sudo nixos-rebuild switch --rollback
-```
-
-## Migration Path
-
-### Phase 1: Minimal Deployment (Current)
-- Basic system config
-- Shared modules for dev tools
-- Symlinks to existing dotfiles
-- **Status**: Complete
-
-### Phase 2: Enhanced Modules (Optional)
-- Language-specific dev environments
-- More application configurations via Nix
-- Platform-specific optimizations
-
-### Phase 3: Advanced Features (Optional)
-- Custom NixOS modules
-- Per-project development shells
-- CI/CD integration
-
-### Phase 4: Full Declarative (Optional)
-- All applications via Nix
-- Automated backups
-- Declarative VM/container configs
-
-## Next Steps
-
-### Immediate
-1. **Test on target platforms**: Deploy to WSL2, native NixOS, or Archlinux
-2. **Customize user info**: Update git username/email in home configs
-3. **Adjust packages**: Add/remove packages in modules as needed
-
-### Short Term
-1. **Generate hardware config**: For native NixOS deployment
-2. **Customize desktop**: Choose desktop environment, graphics drivers
-3. **Add more dotfiles**: Follow pattern in terminal.nix for new apps
-
-### Long Term
-1. **Secrets management**: Manually manage SSH keys and sensitive credentials
-2. **CI/CD**: Add GitHub Actions to test flake
-3. **Development shells**: Create per-project flake.nix files
-4. **Documentation**: Add your own notes and customizations
-
-## Troubleshooting Common Issues
-
-### "experimental features not enabled"
-**Solution**: Add to NixOS config or `~/.config/nix/nix.conf`:
-```
-experimental-features = nix-command flakes
-```
-
-### Conflicting files
-**Solution**: Backup existing files before deploying:
-```bash
-mv ~/.config/nvim ~/.config/nvim.backup
-```
-
-### Module not found
-**Solution**: Check import paths are relative to file location
-
-### Package not available
-**Solution**: Search at search.nixos.org, verify attribute path
-
-## Files Summary
-
-Total files created: **19 Nix files + 4 documentation files**
-
-**Nix Configuration**:
-- 1 flake.nix
-- 3 system configurations (wsl, native, darwin)
-- 4 home configurations (wsl, native, arch, darwin)
-- 6 shared modules (common, shell, dev-tools, neovim, terminal, editors)
-
-**Documentation**:
-- DEPLOYMENT.md (detailed deployment guide)
-- ARCHITECTURE.md (design documentation)
-- QUICK_REFERENCE.md (command cheat sheet)
-- README.nix.md (user-facing README)
-- IMPLEMENTATION_SUMMARY.md (this file)
-
-**Modified**:
-- .gitignore (added hardware-configuration.nix exclusion)
-
-## Success Criteria
-
-This implementation is successful if:
-
-1. **Reproducible**: Same command produces same environment on any platform
-2. **Modular**: Can enable/disable modules independently
-3. **Flexible**: Works on NixOS and non-NixOS systems
-4. **Maintainable**: Easy to add packages, modules, or platforms
-5. **Documented**: Clear instructions for deployment and customization
-6. **Preserves existing workflow**: Dotfiles can still be edited directly
-
-All criteria have been met with this implementation.
-
----
-
-**You now have a fully functional, reproducible, cross-platform dotfiles setup using Nix flakes!**
-
-Deploy with:
-- **NixOS WSL2**: `sudo nixos-rebuild switch --flake .#nixos-wsl`
-- **NixOS Native**: `sudo nixos-rebuild switch --flake .#nixos-native`
-- **Archlinux**: `home-manager switch --flake .#user@linux`
+# Current Configuration Summary
+
+| Platform | Managed by this repository | Not managed |
+| --- | --- | --- |
+| NixOS WSL2 | System, integrated Home Manager, packages, mutable config links, bootstrap checkout | Windows terminal setup |
+| Native NixOS | System, integrated Home Manager, packages, mutable config links | Automatic hardware discovery or disk installation |
+| macOS | Brewfile package installation and GNU Stow links | Nix configuration or macOS system preferences |
+| Arch Linux | Root pacman package list and GNU Stow links | Nix configuration or system services |
+
+The NixOS outputs target x86_64. Linux x86_64 and ARM64 have repository quality
+checks, a formatter, and a development shell. There are no standalone Home
+Manager or Darwin outputs.
+
+## Shared files, separate package sets
+
+Application files remain Stow-compatible. NixOS links them with Home Manager's
+`mkOutOfStoreSymlink`; macOS and Arch link them with Stow. NixOS expects the
+checkout at `/home/user3301/dotfiles`.
+
+The eight Home Manager modules cover common settings, shells, development
+tools, Git, Neovim, terminal tools, WezTerm, and language toolchains. They are
+used only by the NixOS homes. Native package manifests are independent and
+smaller; installing one does not reproduce the entire NixOS environment.
+
+Nix package sources are locked in `flake.lock`. Mutable config files,
+Homebrew/pacman packages, Neovim plugin installation, Herdr plugins, and secrets
+are not made reproducible by that lockfile.
+
+CI already runs GitHub Actions linting, four Nix flake quality checks, and WSL
+configuration evaluation. It does not deploy machines or install native
+macOS/Arch packages.
+
+## Documentation map
+
+| Guide | Purpose |
+| --- | --- |
+| [Deployment](DEPLOYMENT.md) | Platform setup, hardware, dependencies, local overrides |
+| [NixOS](README.nix.md) | Rebuilds, updates, rollback, garbage collection |
+| [Architecture](ARCHITECTURE.md) | Modules, outputs, symlinks, CI |
+| [Quick reference](QUICK_REFERENCE.md) | Common commands and file locations |
+| [Version pinning](EXAMPLE-VERSION-PINNING.md) | Current Nix package overrides |
diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md
index 1bb5153..738b338 100644
--- a/docs/QUICK_REFERENCE.md
+++ b/docs/QUICK_REFERENCE.md
@@ -1,474 +1,112 @@
-# Quick Reference Guide
+# Quick Reference
 
-## Bootstrap (First-Time Setup on Clean NixOS)
+Run checkout commands from `~/dotfiles`. Read [deployment](DEPLOYMENT.md) for
+prerequisites and conflict handling before the first setup.
 
-**Problem**: No git on fresh NixOS install, but need git to clone dotfiles.
+## macOS and Arch Linux
 
-**Solution**:
-```bash
-# Get temporary git
-nix-shell -p git
-# or
-nix run nixpkgs#git -- clone https://github.com/user3301/dotfiles.git ~/dotfiles
+| Task | macOS | Arch Linux |
+| --- | --- | --- |
+| Install/update manifest packages | `brew bundle --file=Brewfile` | `sudo pacman -Syu --needed - < pacman-packages.txt` |
+| Install packages and link dotfiles | `make setup-mac` | `make setup-arch` |
+| Package manifest | `Brewfile` | `pacman-packages.txt` |
 
-# Clone and deploy
-cd ~/dotfiles
-sudo nixos-rebuild switch --flake .#nixos-wsl  # or .#nixos-native
-exit  # Exit nix-shell if used
-
-# Now git is permanently installed!
-```
-
-See full bootstrap guide in [DEPLOYMENT.md](DEPLOYMENT.md#bootstrap-process-first-time-setup-on-clean-nixos).
-
----
+Homebrew must already be on `PATH` for `make setup-mac`. Stow does not install
+shell frameworks or missing applications; the manifests are not the full NixOS
+package set.
 
-## Common Commands by Platform
+```sh
+# Default non-AeroSpace links
+make stow
 
-### NixOS WSL2
+# Select only desired packages
+make stow STOW_PACKAGES="git nvim"
 
-```bash
-# Deploy/update system
-sudo nixos-rebuild switch --flake .#nixos-wsl
+# Preview a selection
+stow --simulate --verbose --target="$HOME" git nvim
 
-# Test without switching
-sudo nixos-rebuild test --flake .#nixos-wsl
+# Remove only Stow-managed links for a selection
+stow --delete --target="$HOME" git nvim
 
-# Build without activating
-sudo nixos-rebuild build --flake .#nixos-wsl
-
-# Show what will change
-sudo nixos-rebuild dry-run --flake .#nixos-wsl
-
-# Rollback to previous generation
-sudo nixos-rebuild switch --rollback
-
-# List generations
-sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
+# macOS-only configuration
+stow --target="$HOME" aerospace
 ```
 
-### NixOS Native
+`make stow` selects `bash fastfetch git herdr lazygit nvim wezterm yazi zsh`.
+`make setup-mac` adds `aerospace`. Do not Stow paths managed by Home Manager.
 
-```bash
-# Deploy/update system
-sudo nixos-rebuild switch --flake .#nixos-native
-
-# Same options as WSL2 (test, build, dry-run, rollback)
-```
-
-### Archlinux (or other Linux with Home Manager)
-
-```bash
-# First-time setup (if home-manager not installed)
-nix run home-manager/master -- switch --flake .#user@linux
+## NixOS WSL2
 
-# Update configuration
-home-manager switch --flake .#user@linux
+```sh
+# Bootstrap an existing NixOS-WSL installation
+nix --extra-experimental-features 'nix-command flakes' run github:user3301/dotfiles#bootstrap-wsl
 
-# Test without switching
-home-manager build --flake .#user@linux
-./result/activate
-
-# List generations
-home-manager generations
+# After restarting WSL from PowerShell with wsl --shutdown:
+cd ~/dotfiles
+make switch
 
-# Rollback
-home-manager switch --rollback
+# Build without activation
+make build
 
-# Or rollback to specific generation
-/nix/var/nix/profiles/per-user/$USER/home-manager-42-link/activate
+# Update locked inputs, then rebuild
+make update
+make switch
 ```
 
-### macOS (nix-darwin)
+For an existing checkout, `make setup-wsl-nixos` stages the configuration with
+`nixos-rebuild boot`; it requires a WSL restart.
 
-```bash
-# Deploy/update (Apple Silicon)
-darwin-rebuild switch --flake .#aarch64
+## Native NixOS
 
-# Deploy/update (Intel)
-darwin-rebuild switch --flake .#x86_64
+Replace the VirtualBox hardware import before deploying to another machine.
 
-# Using Makefile
-make update-home-manager
+```sh
+sudo nixos-rebuild build --flake .#nixos-native
+sudo nixos-rebuild switch --flake .#nixos-native
 ```
 
-## Flake Management
+## Nix maintenance
 
-```bash
-# Update all inputs
-nix flake update
-
-# Update specific input
-nix flake lock --update-input nixpkgs
-nix flake lock --update-input home-manager
-
-# Show flake info
+```sh
 nix flake show
-
-# Check for errors
-nix flake check
-
-# Show flake metadata
-nix flake metadata
-```
-
-## Package Management
-
-### Search for packages
-
-```bash
-# Online search (recommended)
-# Visit: https://search.nixos.org/packages
-
-# Command line search
-nix search nixpkgs <package-name>
-
-# Example
-nix search nixpkgs neovim
-```
-
-### Install package temporarily
-
-```bash
-# Run without installing
-nix run nixpkgs#hello
-
-# Start shell with package
-nix shell nixpkgs#hello nixpkgs#cowsay
-
-# Run specific version
-nix run github:nixos/nixpkgs/nixos-23.11#hello
-```
-
-### Add package permanently
-
-Edit appropriate file:
-
-**System packages** (NixOS only):
-```nix
-# systems/{wsl,native}/configuration.nix
-environment.systemPackages = with pkgs; [
-  mypackage
-];
-```
-
-**User packages** (all platforms):
-```nix
-# home/modules/dev-tools.nix or platform-specific home config
-home.packages = with pkgs; [
-  mypackage
-];
-```
-
-Then rebuild:
-```bash
-# NixOS
-sudo nixos-rebuild switch --flake .#nixos-wsl
-
-# Home Manager (Archlinux, etc.)
-home-manager switch --flake .#user@linux
-```
-
-## Editing Configurations
-
-### File locations
-
-| What | Where |
-|------|-------|
-| Main flake | `/Users/gaiz/dotfiles/flake.nix` |
-| WSL system | `/Users/gaiz/dotfiles/systems/wsl/configuration.nix` |
-| Native system | `/Users/gaiz/dotfiles/systems/native/configuration.nix` |
-| WSL home | `/Users/gaiz/dotfiles/home/nixos-wsl.nix` |
-| Native home | `/Users/gaiz/dotfiles/home/nixos-native.nix` |
-| Arch home | `/Users/gaiz/dotfiles/home/archlinux.nix` |
-| Common module | `/Users/gaiz/dotfiles/home/modules/common.nix` |
-| Dev tools | `/Users/gaiz/dotfiles/home/modules/dev-tools.nix` |
-
-### Editing workflow
-
-```bash
-# 1. Edit configuration files
-vim ~/dotfiles/home/modules/dev-tools.nix
-
-# 2. Check for syntax errors
 nix flake check
-
-# 3. Test the changes
-sudo nixos-rebuild test --flake .#nixos-wsl
-
-# 4. If good, apply permanently
-sudo nixos-rebuild switch --flake .#nixos-wsl
-
-# 5. Commit changes
-git add .
-git commit -m "Add new package"
-git push
-```
-
-## Dotfiles Management
-
-### Symlinked configs
-
-Your existing dotfiles are symlinked from:
-- `~/dotfiles/nvim/.config/nvim` → `~/.config/nvim`
-- `~/dotfiles/herdr/.config/herdr` → `~/.config/herdr`
-- `~/dotfiles/wezterm/.config/wezterm` → `~/.config/wezterm`
-- etc.
-
-You can edit them directly:
-```bash
-# Edit neovim config
-vim ~/dotfiles/nvim/.config/nvim/init.lua
-
-# Changes are immediately available (no rebuild needed)
-```
-
-### Adding new dotfile
-
-1. Add directory structure:
-```bash
-mkdir -p ~/dotfiles/myapp/.config/myapp
-cp -r ~/.config/myapp/* ~/dotfiles/myapp/.config/myapp/
-```
-
-2. Create or update module:
-```nix
-# home/modules/myapp.nix
-{ config, pkgs, lib, ... }:
-{
-  programs.myapp.enable = true;
-
-  xdg.configFile."myapp".source = config.lib.file.mkOutOfStoreSymlink
-    "${config.home.homeDirectory}/dotfiles/myapp/.config/myapp";
-}
-```
-
-3. Import in home config:
-```nix
-# home/nixos-wsl.nix
-imports = [
-  ./modules/common.nix
-  ./modules/myapp.nix
-];
-```
-
-4. Rebuild
-
-## Garbage Collection
-
-```bash
-# Delete old generations (7+ days)
-nix-collect-garbage --delete-older-than 7d
-
-# Delete all old generations (NixOS)
-sudo nix-collect-garbage -d
-
-# Delete all old generations (Home Manager)
-nix-collect-garbage -d
-
-# Remove old boot entries (NixOS)
-sudo nix-env --delete-generations old --profile /nix/var/nix/profiles/system
-sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot
-
-# Optimize store (remove duplicate files)
-nix-store --optimise
-```
-
-## Troubleshooting
-
-### Build failures
-
-```bash
-# Show detailed error
-nix build --show-trace .#nixosConfigurations.nixos-wsl.config.system.build.toplevel
-
-# Clean build cache
-nix-collect-garbage -d
-sudo nix-collect-garbage -d
-```
-
-### Conflicting files
-
-```bash
-# Find conflicts
-home-manager switch --flake .#user@linux
-
-# If it shows conflicting files, back them up
-mv ~/.config/nvim ~/.config/nvim.backup
-
-# Then rebuild
-home-manager switch --flake .#user@linux
-```
-
-### Rollback
-
-```bash
-# NixOS: List generations
-sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
-
-# NixOS: Switch to generation 42
-sudo nix-env --switch-generation 42 --profile /nix/var/nix/profiles/system
-sudo /nix/var/nix/profiles/system/bin/switch-to-configuration switch
-
-# Home Manager: List generations
-home-manager generations
-
-# Home Manager: Activate generation
-/nix/var/nix/profiles/per-user/$USER/home-manager-42-link/activate
-```
-
-### Reset to clean state
-
-```bash
-# ⚠️  DESTRUCTIVE: This will remove all Nix-installed packages
-
-# Remove all generations
-nix-collect-garbage -d
-sudo nix-collect-garbage -d
-
-# Reinstall from scratch
-cd ~/dotfiles
-sudo nixos-rebuild switch --flake .#nixos-wsl
-```
-
-## Platform-Specific Quick Tips
-
-### WSL2
-
-```bash
-# Access Windows files
-cd /mnt/c/Users/YourName
-
-# Run Windows command
-cmd.exe /c dir
-
-# Open file in Windows app
-explorer.exe .
-```
-
-### Archlinux
-
-```bash
-# Update both Arch and Nix packages
-sudo pacman -Syu && home-manager switch --flake .#user@linux
-
-# Install system package (use pacman)
-sudo pacman -S docker
-
-# Install dev tool (use Nix)
-# Add to home/modules/dev-tools.nix, then:
-home-manager switch --flake .#user@linux
-```
-
-### macOS
-
-```bash
-# Update Homebrew apps
-brew update && brew upgrade
-
-# Update Nix configuration
-darwin-rebuild switch --flake .#aarch64
-
-# Both
-brew upgrade && darwin-rebuild switch --flake .#aarch64
-```
-
-## Development Shells
-
-### Project-specific environment
-
-Create `flake.nix` in project directory:
-
-```nix
-{
-  description = "My project";
-
-  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-
-  outputs = { self, nixpkgs }:
-    let
-      system = "x86_64-linux";
-      pkgs = import nixpkgs { inherit system; };
-    in {
-      devShells.${system}.default = pkgs.mkShell {
-        buildInputs = with pkgs; [
-          nodejs
-          python3
-          postgresql
-        ];
-      };
-    };
-}
-```
-
-Enter shell:
-```bash
 nix develop
-```
-
-Or use direnv:
-```bash
-echo "use flake" > .envrc
-direnv allow
-# Now auto-loads when you cd into directory
-```
-
-## Useful Environment Variables
-
-```bash
-# See what's in your PATH
-echo $PATH
+nix fmt -- flake.nix
 
-# See all Nix profiles
-ls -la ~/.nix-profile/
-
-# See current system profile (NixOS)
-ls -la /run/current-system
-
-# See current home-manager profile
-ls -la ~/.local/state/home-manager/
-
-# NIX_PATH (usually not needed with flakes)
-echo $NIX_PATH
-```
-
-## Getting Help
-
-```bash
-# NixOS options search
-https://search.nixos.org/options
-
-# Home Manager options search
-https://mipmip.github.io/home-manager-option-search/
-
-# Nix command help
-nix --help
-nix build --help
-
-# Man pages
-man configuration.nix
-man home-configuration.nix
-```
-
-## Cheat Sheet
-
-| Task | NixOS | Home Manager (Arch) |
-|------|-------|---------------------|
-| Deploy | `sudo nixos-rebuild switch --flake .#nixos-wsl` | `home-manager switch --flake .#user@linux` |
-| Test | `sudo nixos-rebuild test --flake .#nixos-wsl` | `home-manager build --flake .#user@linux; ./result/activate` |
-| Rollback | `sudo nixos-rebuild switch --rollback` | `home-manager switch --rollback` |
-| Update | `nix flake update` | `nix flake update` |
-| GC | `sudo nix-collect-garbage -d` | `nix-collect-garbage -d` |
-| List gens | `sudo nix-env --list-generations --profile /nix/var/nix/profiles/system` | `home-manager generations` |
-
----
-
-**Pro tip**: Alias common commands in your shell:
+nix flake update
+nix flake update nixpkgs home-manager
 
-```bash
-# Add to ~/.zshrc or equivalent
-alias nrs="sudo nixos-rebuild switch --flake ~/dotfiles#nixos-wsl"
-alias nrt="sudo nixos-rebuild test --flake ~/dotfiles#nixos-wsl"
-alias hms="home-manager switch --flake ~/dotfiles#user@linux"
-alias nfu="nix flake update"
-```
+sudo nixos-rebuild switch --rollback
+sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
+nix-collect-garbage
+```
+
+`nixos-rebuild test --flake .#nixos-wsl` activates temporarily; `build` does not.
+System rollback does not revert linked files in the mutable checkout.
+`make clean` deletes generations older than seven days and runs GC; use it only
+when those rollback points are no longer needed.
+
+Home Manager is integrated into the NixOS rebuild, not exposed as a standalone
+flake output.
+
+## Where to edit
+
+| Change | File |
+| --- | --- |
+| Nix inputs, overlays, outputs, checks | `flake.nix` |
+| WSL system services/user | `systems/wsl/configuration.nix` |
+| Native hardware import/desktop/services | `systems/native/configuration.nix` |
+| NixOS user identity/platform packages | `home/nixos-wsl.nix`, `home/nixos-native.nix` |
+| Shared NixOS user packages | `home/modules/` |
+| Application settings | Respective Stow package |
+| Local Git identity/signing | `git/.config/git/config.local` (ignored) |
+| Local Zsh settings | `zsh/.zshenv.local` (ignored) |
+| Local interactive Bash settings | `bash/.bashrc.local` (ignored) |
+
+Reload applications after editing their linked config. Rebuild NixOS for Nix
+changes; rerun Stow for new linked paths. Use `git add` for new files that a
+Git-backed flake must include.
+
+`make help` lists the available helpers. Full CI commands are in
+[Architecture](ARCHITECTURE.md#existing-ci); package override details are in
+[Version pinning](EXAMPLE-VERSION-PINNING.md).
diff --git a/docs/README.nix.md b/docs/README.nix.md
index 2fc0432..683d89a 100644
--- a/docs/README.nix.md
+++ b/docs/README.nix.md
@@ -1,365 +1,135 @@
-# Cross-Platform Dotfiles with Nix Flakes
+# NixOS Dotfiles
 
-Fully reproducible dotfiles configuration supporting:
-- **NixOS WSL2** (Windows Subsystem for Linux)
-- **NixOS Native** (bare metal or VM)
-- **Archlinux** with Nix + Home Manager
-- **macOS** with nix-darwin
+Nix manages **native NixOS and NixOS WSL2 only**. For macOS (Homebrew + Stow) or
+Arch Linux (pacman + Stow), use the [deployment guide](DEPLOYMENT.md).
 
-> "Dotfiles managed by Nix: because spending 40 hours to save 4 minutes is a lifestyle. Fully reproducible - I've tested it on my Windows gaming rig (NixOS-WSL2), my wife's MacBook Air, and my own laptop (I use Arch BTW). If it works there, it'll work anywhere."
+## First deployment
 
-## Quick Start
+The repository includes `flake.lock`; use those revisions for the initial
+deployment rather than updating inputs immediately.
 
-For Nix installation prerequisites and alternative installers, see the [deployment guide](DEPLOYMENT.md#prerequisites). The repository includes `flake.lock`; use it for the initial deployment rather than updating package versions.
+On an existing NixOS-WSL distribution:
 
-After the first Nix build on a new machine, manually install the Herdr plugins [Auto Title](https://github.com/kryptamine/herdr-auto-title) and [reviewr](https://github.com/persiyanov/herdr-reviewr). These two plugins are not managed by Nix.
-
-Choose your platform:
-
-### NixOS WSL2
-
-On a fresh NixOS-WSL installation, run:
-
-```bash
+```sh
 nix --extra-experimental-features 'nix-command flakes' run github:user3301/dotfiles#bootstrap-wsl
 ```
 
-`nixos-anywhere` is not used here because WSL has already created and mounted
-the distribution's virtual disk; `nixos-anywhere` is intended to provision an
-SSH target and normally repartition its disks.
+This creates the `user3301` configuration and clones the mutable checkout into
+`/home/user3301/dotfiles` before Home Manager activation. Restart with
+`wsl --shutdown` from PowerShell and reopen the distribution.
 
-The bootstrap configuration clones the repository to
-`/home/user3301/dotfiles` as part of NixOS activation, before Home Manager
-starts. This remains reliable even when changing WSL's default user terminates
-the original shell session. It is safe to rerun after an interrupted bootstrap.
-When it completes, run `wsl --shutdown` from PowerShell and reopen the
-distribution.
+For native NixOS, first clone the checkout and replace the checked-in
+VirtualBox hardware import as described in
+[Native NixOS deployment](DEPLOYMENT.md#native-nixos). Then:
 
-### NixOS Native
-```bash
-git clone <your-repo> ~/dotfiles
-cd ~/dotfiles
-
-# Generate hardware config first
-sudo nixos-generate-config --show-hardware-config > systems/native/hardware-configuration.nix
-
-# Edit systems/native/configuration.nix to uncomment hardware import
-# Then deploy
+```sh
 sudo nixos-rebuild switch --flake .#nixos-native
 ```
 
-### Archlinux + Nix/Home Manager
-
-Also suitable for other Linux distributions. Check your architecture with `uname -m` and choose the matching command below.
+Both host configurations are x86_64 and integrate Home Manager. There is no
+separate `home-manager switch --flake` workflow. Most packages and application
+links are defined in `home/modules/`; system settings are under `systems/`.
 
-```bash
-# Install Nix first
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
+## Editing and applying changes
 
-git clone https://github.com/user3301/dotfiles.git ~/dotfiles
+```sh
 cd ~/dotfiles
 
-# Edit home/archlinux.nix to set home.username and home.homeDirectory
-# Then deploy on x86_64 Linux:
-nix run home-manager/master -- switch --flake .#user@linux
-
-# Or on ARM64 Linux:
-nix run home-manager/master -- switch --flake .#user@linux-arm64
-```
-
-The `user@linux` and `user@linux-arm64` names are fixed flake outputs, not placeholders for your username.
-
-### macOS + nix-darwin
-
-From the repository checkout, install Nix, activate nix-darwin with Home Manager, and install Homebrew apps:
-
-```bash
-make setup-mac
-```
-
-If Nix is already installed, activate the Nix configuration directly instead:
-
-```bash
-uname -m
-
-# Apple Silicon (uname -m reports arm64):
-nix run nix-darwin -- switch --flake .#aarch64
-
-# Intel (uname -m reports x86_64):
-nix run nix-darwin -- switch --flake .#x86_64
-```
-
-Before activation, customize `home.username` and `home.homeDirectory` in `home/darwin.nix` and the corresponding `home-manager.users` key in `flake.nix` if needed. Usernames and home directories are configured explicitly, not detected from `$USER`. Home Manager is integrated with nix-darwin; this flake does not provide standalone macOS Home Manager outputs.
-
-## What's Included
-
-### Development Tools
-- **Editors**: Neovim
-- **Terminal**: Herdr, Wezterm, Yazi
-- **Shell**: Zsh (primary, oh-my-zsh + mcfly) with a minimal Bash fallback (zoxide + mcfly)
-- **Version Control**: Git, GitHub CLI, Lazygit
-- **CLI Tools**: ripgrep, fd, bat, fzf, jq, and more
-- **Rust Toolchain**: rustc, Cargo, Clippy, and rustfmt (managed by Nix)
-- **Language Servers**: For Nix, Lua, TypeScript, Python, Rust, Go
+# WSL: rebuild the system and integrated home together
+make switch
 
-### Configuration Management
-- **Modular**: Shared modules + platform-specific overrides
-- **Symlinked**: Your existing dotfiles are symlinked (edit directly, no rebuild needed)
-- **Stow-compatible**: each top-level config directory is also a GNU Stow package, so the same repo works on non-Nix machines (`stow bash zsh nvim`)
-- **Reproducible**: Same environment across all machines
-- **Declarative**: Everything in version control
-
-## Directory Structure
-
-```
-dotfiles/
-├── flake.nix                    # Main configuration entry point
-│
-├── home/                        # Home Manager configurations
-│   ├── modules/                 # Shared modules
-│   │   ├── common.nix          # Base settings
-│   │   ├── shell.nix           # Zsh + Bash configuration
-│   │   ├── dev-tools.nix       # Development packages
-│   │   ├── neovim.nix          # Neovim + LSPs
-│   │   └── terminal.nix        # Herdr, Wezterm, Yazi
-│   │
-│   ├── nixos-wsl.nix           # WSL2 home config
-│   ├── nixos-native.nix        # Native NixOS home config
-│   ├── archlinux.nix           # Archlinux home config
-│   └── darwin.nix              # macOS home config
-│
-├── systems/                     # NixOS system configurations
-│   ├── wsl/
-│   │   └── configuration.nix   # WSL2 system config
-│   ├── native/
-│   │   └── configuration.nix   # Native NixOS system config
-│   └── darwin/
-│       └── configuration.nix   # macOS system config
-│
-├── [existing dotfiles]/         # Your actual configs
-│   ├── nvim/.config/nvim/
-│   ├── herdr/.config/herdr/
-│   ├── wezterm/.config/wezterm/
-│   ├── yazi/.config/yazi/
-│   ├── zsh/
-│   └── bash/                    # Minimal fallback shell
-│
-└── docs/
-    ├── DEPLOYMENT.md           # Detailed deployment guide
-    ├── ARCHITECTURE.md         # Architecture documentation
-    └── QUICK_REFERENCE.md      # Command cheat sheet
+# Native NixOS
+sudo nixos-rebuild switch --flake .#nixos-native
 ```
 
-## Documentation
+Edit shared user packages in the appropriate `home/modules/*.nix` file, or
+platform packages in `home/nixos-wsl.nix` / `home/nixos-native.nix`. Add new
+modules to the selected home's imports. Git-backed flakes exclude new,
+untracked files until they are added with `git add`.
 
-- **[DEPLOYMENT.md](DEPLOYMENT.md)**: Detailed deployment instructions for each platform
-- **[ARCHITECTURE.md](ARCHITECTURE.md)**: Architecture design and rationale
-- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)**: Command cheat sheet and quick tips
+Application configuration is linked to the checkout, so editing Lua, TOML,
+shell, or Git config normally only needs an application reload. Do not Stow
+over the links managed by Home Manager. Git identity belongs in the ignored
+`git/.config/git/config.local`, not a generated `programs.git` configuration.
 
-## Common Tasks
-
-### Update Configuration
-```bash
-# NixOS
-cd ~/dotfiles
-sudo nixos-rebuild switch --flake .#nixos-wsl
+Keep `system.stateVersion` and `home.stateVersion` at their existing values
+unless you have reviewed the relevant migration guidance. They select
+compatibility defaults; they are not the package channel version.
 
-# Archlinux / other Linux (use .#user@linux-arm64 on ARM64)
-cd ~/dotfiles
-home-manager switch --flake .#user@linux
+## Updating packages
 
-# macOS Apple Silicon (use .#x86_64 on Intel)
+```sh
 cd ~/dotfiles
-darwin-rebuild switch --flake .#aarch64
-```
+nix flake update                  # all inputs
+# Or update only selected inputs:
+nix flake update nixpkgs home-manager
 
-### Add New Package
-Edit `home/modules/dev-tools.nix`:
-```nix
-home.packages = with pkgs; [
-  # Add your package here
-  htop
-];
+sudo nixos-rebuild switch --flake .#nixos-wsl
+# Use .#nixos-native for the native host
 ```
-Then rebuild.
 
-### Update All Packages
-```bash
-nix flake update
-```
+Review and commit `flake.lock` alongside intentional input changes. Updating
+the lockfile alone does not activate packages. The Azure CLI revision and
+Copilot CLI version/hash override require deliberate edits; see
+[version pinning](EXAMPLE-VERSION-PINNING.md).
 
-Then run your platform's command under [Update Configuration](#update-configuration) to activate the updated packages. Commit the updated `flake.lock` to keep package versions reproducible.
+`make update` updates inputs; `make upgrade` updates and rebuilds WSL.
+`make switch`, `make build`, and `make upgrade` are WSL-specific, not host
+auto-detection commands.
 
-### Inspect the Flake and Search Packages
-```bash
-# Check the configuration
-nix flake check
+## Validation and troubleshooting
 
-# Show available outputs
+```sh
 nix flake show
+nix flake check
 
-# Search for a package
-nix search nixpkgs <package-name>
-```
-
-### Rollback
-```bash
-# NixOS
-sudo nixos-rebuild switch --rollback
-
-# Home Manager
-home-manager switch --rollback
-```
-
-## Platform-Specific Features
-
-### NixOS WSL2
-- Full NixOS experience on Windows
-- WSL interoperability enabled
-- Windows paths accessible via `/mnt/c/`
-- Username: `user3301`
-
-### NixOS Native
-- Full system control
-- Hardware configuration included
-- Desktop environment support
-- Username: `user3301`
-
-### Archlinux + Nix/Home Manager
-- Best of both worlds (pacman + Nix)
-- System packages via pacman
-- User packages via Nix
-- Gradual migration path
-
-### macOS + nix-darwin
-- System settings via Nix
-- GUI apps via Homebrew (Brewfile)
-- User configs via Home Manager
-
-## Design Principles
-
-1. **Reproducibility**: Same command, same result, every time
-2. **Modularity**: Shared code across platforms, platform-specific when needed
-3. **Flexibility**: Works on NixOS and non-NixOS systems
-4. **Familiarity**: Preserves your existing dotfiles structure
-5. **Separation**: System vs. user configuration
-
-## Advanced Features
-
-### Secrets Management
-**Current approach**: Manual management for simplicity
-- Generate SSH keys manually on each machine: `ssh-keygen -t ed25519`
-- Keep sensitive credentials outside version control
-- Use local overrides (`.zshenv.local` / `.bashrc.local` pattern) for machine-specific secrets
-
-### Development Shells
-Create project-specific environments:
-```nix
-# In your project directory
-{
-  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-  outputs = { nixpkgs, ... }: {
-    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
-      buildInputs = [ nodejs python3 ];
-    };
-  };
-}
-```
-
-Then: `nix develop`
+# Build without activation
+sudo nixos-rebuild build --flake .#nixos-wsl
 
-### CI/CD
-Add GitHub Actions to test configurations:
-```yaml
-- name: Check flake
-  run: nix flake check
+# Evaluate with a trace if necessary
+nix eval --show-trace --raw \
+  '.#nixosConfigurations.nixos-wsl.config.system.build.toplevel.drvPath'
 ```
 
-## Troubleshooting
+`nixos-rebuild test` **does activate** the configuration, but does not make it
+the boot default. Use `build` when you want no running-system changes.
 
-### "experimental features not enabled"
-```bash
-# NixOS: Add to configuration.nix
-nix.settings.experimental-features = [ "nix-command" "flakes" ];
+CI's narrower quality/evaluation commands are listed in
+[Architecture](ARCHITECTURE.md#existing-ci). Native hardware must be reviewed
+on the target machine even if evaluation succeeds.
 
-# Non-NixOS: Add to ~/.config/nix/nix.conf
-experimental-features = nix-command flakes
-```
+For initial commands on a system without flakes enabled, use
+`nix --extra-experimental-features 'nix-command flakes' ...`. The bootstrap app
+also enables those features for its rebuild.
 
-### Conflicting files
-```bash
-# Backup existing configs
-mv ~/.config/nvim ~/.config/nvim.backup
+If Home Manager reports a file conflict, inspect and back up that specific
+path, then rebuild. Do not force replacement of the entire `~/.config`
+directory. Inspect activation failures with:
 
-# Then rebuild
-home-manager switch --flake .#user@linux
+```sh
+journalctl -u home-manager-user3301.service -b
 ```
 
-### Build errors
-```bash
-# Show detailed trace
-nix build --show-trace .#nixosConfigurations.nixos-wsl.config.system.build.toplevel
+## Rollback and garbage collection
 
-# Clean and rebuild
-nix-collect-garbage -d
-sudo nixos-rebuild switch --flake .#nixos-wsl
+```sh
+sudo nixos-rebuild switch --rollback
+make generations
+make gc
 ```
 
-## Migration Guide
-
-### From existing non-Nix setup
-1. Start with minimal configuration
-2. Add modules incrementally
-3. Test each change
-4. Keep backups during transition
-
-### From NixOS without flakes
-1. Enable flakes in current config
-2. Rebuild with `nixos-rebuild switch`
-3. Clone this repo
-4. Switch to flake: `sudo nixos-rebuild switch --flake .#nixos-wsl`
-
-### From home-manager without flakes
-1. Backup current config
-2. Install from this repo
-3. Gradually migrate custom settings
-
-## Contributing
-
-Feel free to:
-- Report issues
-- Suggest improvements
-- Share your configurations
-- Submit pull requests
-
-## Resources
-
-- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
-- [Home Manager Manual](https://nix-community.github.io/home-manager/)
-- [Nix Pills](https://nixos.org/guides/nix-pills/)
-- [NixOS Discourse](https://discourse.nixos.org/)
-- [NixOS Wiki](https://nixos.wiki/)
-
-## FAQ
-
-**Q: Why Nix?**
-A: Reproducibility, declarative configuration, and one package manager to rule them all.
-
-**Q: Can I use this on Ubuntu/Fedora?**
-A: Yes! Use the Archlinux configuration as a template (standalone Home Manager).
-
-**Q: Do I need to use Nix for everything?**
-A: No. You can keep using your OS package manager for system packages and use Nix for user-level tools.
-
-**Q: What if I want to customize?**
-A: All configurations are modular. Edit the relevant module or create a new one.
-
-**Q: How do I update packages?**
-A: `nix flake update` updates all inputs, then rebuild your configuration.
+Integrated Home Manager packages and generated configuration belong to the
+system generation. Mutable symlink targets are not rolled back; restore
+application files separately from Git if necessary.
 
-**Q: Can I test changes without breaking my system?**
-A: Yes! Use `sudo nixos-rebuild test` or `home-manager build` to test first.
+Both NixOS systems enable weekly garbage collection with seven-day retention.
+`make clean` runs `sudo nix-collect-garbage --delete-older-than 7d`; this removes
+older system generations and can eliminate rollback options. It is not a
+build-error recovery step.
 
----
+## Manual components
 
-**Remember**: The goal is reproducibility. Once configured, you can deploy this exact environment on any new machine with a single command!
+LazyVim downloads plugins independently of Nix. Herdr's Auto Title and reviewr
+plugins need manual installation. SSH keys, signing keys, and credentials are
+not provisioned. See [deployment](DEPLOYMENT.md#local-settings-and-manual-steps)
+and the [Neovim README](../nvim/.config/nvim/README.md).
diff --git a/flake.lock b/flake.lock
index 16fb6c4..af5a890 100644
--- a/flake.lock
+++ b/flake.lock
@@ -79,26 +79,6 @@
         "type": "github"
       }
     },
-    "nix-darwin": {
-      "inputs": {
-        "nixpkgs": [
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1786845137,
-        "narHash": "sha256-oQFip+v0luP8NIxJzmiW4Wu8bILsbFWom5l0zonl8hQ=",
-        "owner": "LnL7",
-        "repo": "nix-darwin",
-        "rev": "4cff07de74b50e64bdd68cd4e722ab5b6b35ee48",
-        "type": "github"
-      },
-      "original": {
-        "owner": "LnL7",
-        "repo": "nix-darwin",
-        "type": "github"
-      }
-    },
     "nixos-wsl": {
       "inputs": {
         "flake-compat": "flake-compat",
@@ -157,7 +137,6 @@
         "claude-code-nix": "claude-code-nix",
         "herdr": "herdr",
         "home-manager": "home-manager",
-        "nix-darwin": "nix-darwin",
         "nixos-wsl": "nixos-wsl",
         "nixpkgs": "nixpkgs",
         "nixpkgs-azure-cli": "nixpkgs-azure-cli"
diff --git a/flake.nix b/flake.nix
index 3c191f3..d7daf1b 100644
--- a/flake.nix
+++ b/flake.nix
@@ -1,5 +1,5 @@
 {
-  description = "user3301's' dotfiles for NixOS, NixOS WSL2, and Archlinux";
+  description = "user3301's dotfiles for native NixOS and NixOS WSL2";
 
   inputs = {
     # Nixpkgs - stable release
@@ -27,12 +27,6 @@
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Nix Darwin - for macOS support (optional, keeping for your current setup)
-    nix-darwin = {
-      url = "github:LnL7/nix-darwin";
-      inputs.nixpkgs.follows = "nixpkgs";
-    };
-
     # Pinned nixpkgs providing azure-cli 2.77.0 (nixpkgs went 2.75.0 -> 2.77.0
     # directly; 2.76.0 was never packaged). Deliberately not following the
     # main nixpkgs input, since the whole point is to freeze this one package.
@@ -45,15 +39,12 @@
       nixpkgs,
       home-manager,
       nixos-wsl,
-      nix-darwin,
       ...
     }@inputs:
     let
       supportedSystems = [
         "x86_64-linux"
         "aarch64-linux"
-        "x86_64-darwin"
-        "aarch64-darwin"
       ];
       forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
 
@@ -70,8 +61,6 @@
               {
                 "x86_64-linux" = "linux-x64";
                 "aarch64-linux" = "linux-arm64";
-                "x86_64-darwin" = "darwin-x64";
-                "aarch64-darwin" = "darwin-arm64";
               }
               .${prev.stdenv.hostPlatform.system};
           in
@@ -83,8 +72,6 @@
                 {
                   "x86_64-linux" = "sha256-z70Rb+FZviiaut8sK/GKJairCe7KVKCR1AJeHLzaRwk=";
                   "aarch64-linux" = "sha256-saIHbLOlh+uivG9HjONeU/IKNNDWm0GAdDmzMC3191o=";
-                  "x86_64-darwin" = "sha256-biISO2sXX+HWeGo+4vXRu3M9BN839sFBN0McAcPBWNI=";
-                  "aarch64-darwin" = "sha256-Tr+isxFUmWQgQX3ivglJ7x9ONa8JQ9ZVFUdNWuPCKxE=";
                 }
                 .${prev.stdenv.hostPlatform.system};
             };
@@ -123,35 +110,6 @@
           };
         };
 
-      # Helper function for standalone Home Manager (Archlinux, etc.)
-      mkHome =
-        {
-          system,
-          modules,
-        }:
-        home-manager.lib.homeManagerConfiguration {
-          pkgs = import nixpkgs {
-            inherit system;
-            config.allowUnfree = true;
-            overlays = [
-              claudeOverlay
-              copilotOverlay
-              azureCliOverlay
-            ];
-          };
-          inherit modules;
-          extraSpecialArgs = { inherit inputs; };
-        };
-
-      # Helper function for nix-darwin (macOS)
-      mkDarwin =
-        { system, modules }:
-        nix-darwin.lib.darwinSystem {
-          inherit system;
-          inherit modules;
-          specialArgs = { inherit inputs; };
-        };
-
       wslSystemModules = [
         nixos-wsl.nixosModules.wsl
         ./systems/wsl/configuration.nix
@@ -232,25 +190,6 @@
         };
       };
 
-      # Standalone Home Manager Configurations (for Archlinux, etc.)
-      homeConfigurations = {
-        # Generic Linux configuration (Archlinux, Ubuntu, Fedora, etc.)
-        "user@linux" = mkHome {
-          system = "x86_64-linux";
-          modules = [
-            ./home/archlinux.nix
-          ];
-        };
-
-        # ARM64 Linux configuration
-        "user@linux-arm64" = mkHome {
-          system = "aarch64-linux";
-          modules = [
-            ./home/archlinux.nix
-          ];
-        };
-      };
-
       packages.x86_64-linux.bootstrap-wsl =
         let
           pkgs = nixpkgs.legacyPackages.x86_64-linux;
@@ -268,43 +207,6 @@
         program = "${self.packages.x86_64-linux.bootstrap-wsl}/bin/bootstrap-nixos-wsl";
       };
 
-      # macOS configurations (keeping your existing setup)
-      darwinConfigurations = {
-        # macOS Apple Silicon
-        "aarch64" = mkDarwin {
-          system = "aarch64-darwin";
-          modules = [
-            ./systems/darwin/configuration.nix
-            home-manager.darwinModules.home-manager
-            {
-              home-manager = {
-                useGlobalPkgs = true;
-                useUserPackages = true;
-                users.gaiz = import ./home/darwin.nix;
-                extraSpecialArgs = { inherit inputs; };
-              };
-            }
-          ];
-        };
-
-        # macOS Intel
-        "x86_64" = mkDarwin {
-          system = "x86_64-darwin";
-          modules = [
-            ./systems/darwin/configuration.nix
-            home-manager.darwinModules.home-manager
-            {
-              home-manager = {
-                useGlobalPkgs = true;
-                useUserPackages = true;
-                users.gaiz = import ./home/darwin.nix;
-                extraSpecialArgs = { inherit inputs; };
-              };
-            }
-          ];
-        };
-      };
-
       formatter = forAllSystems (system: nixpkgs.legacyPackages.${system}.nixfmt);
 
       checks = forAllSystems (
@@ -388,7 +290,7 @@
             ];
             shellHook = ''
               echo "Dotfiles development environment"
-              echo "Use 'nixos-rebuild' or 'home-manager' commands to apply configurations"
+              echo "Use 'nixos-rebuild' to apply NixOS and Home Manager configurations"
             '';
           };
         }
diff --git a/git/.config/git/README.md b/git/.config/git/README.md
index b1cf506..4ebc3b3 100644
--- a/git/.config/git/README.md
+++ b/git/.config/git/README.md
@@ -1,62 +1,43 @@
 # Git Configuration
 
-This directory contains the shared git configuration that works across all platforms (NixOS, macOS, Linux, WSL).
+`config` is shared by NixOS (Home Manager symlink) and macOS/Arch Linux (GNU
+Stow). It sets Neovim as the editor, delta as the pager/diff filter, `input`
+line-ending conversion, `zdiff3` merge conflicts, and SSH commit signing.
+Install Neovim and delta when using it outside NixOS.
 
-## OS-Specific Configurations
-
-You can create OS-specific git configuration files that will be automatically included:
-
-### Setup
-
-Add the following to the bottom of `config`:
+The tracked identity is a default. Set your own identity and signing key in
+`~/.config/git/config.local`, which is already included **after** the defaults:
 
 ```gitconfig
-# OS-specific configurations
-# These will be loaded if the files exist
-[include]
-	path = ~/.config/git/config.local
-	path = ~/.config/git/config.darwin
-	path = ~/.config/git/config.linux
-	path = ~/.config/git/config.wsl
+[user]
+    name = Your Name
+    email = you@example.com
+    signingkey = ~/.ssh/id_ed25519.pub
 ```
 
-### Create OS-Specific Files
-
-Then create the appropriate files:
-
-- **`config.darwin`** - macOS-specific settings
-- **`config.linux`** - Native Linux-specific settings
-- **`config.wsl`** - WSL-specific settings
-- **`config.local`** - Machine-specific settings (not tracked in git)
-
-### Example OS-Specific Files
+Use an existing SSH signing key or generate one separately; no private keys are
+provided. `commit.gpgsign = true` is enabled, so commits require a usable signing
+key and private-key/agent access. If signing is not wanted on this machine,
+override it explicitly:
 
-**config.darwin:**
 ```gitconfig
-# macOS-specific git configuration
-
-[core]
-	# macOS specific settings
-```
-
-**config.linux:**
-```gitconfig
-# Linux-specific git configuration
-
-[core]
-	# Linux specific settings
+[commit]
+    gpgsign = false
 ```
 
-**config.wsl:**
-```gitconfig
-# WSL-specific git configuration
+`git/.config/git/config.local` is ignored by the repository. When the whole
+config directory is symlinked, creating the local file writes into the checkout;
+keep it untracked. An existing `~/.gitconfig` can override XDG config settings.
+Inspect the source of effective settings with:
 
-[core]
-	# WSL might need different autocrlf handling
+```sh
+git config --show-origin --list
 ```
 
-### Notes
+There are no automatic OS-specific includes. Only `config.local` is included.
+If you add more include paths yourself, Git reads all existing files at those
+paths; names such as `config.darwin` do not cause OS detection.
 
-- Git will silently ignore include paths that don't exist
-- Settings in later files override earlier ones
-- You can add `config.local` to `.gitignore` for machine-specific settings
+`core.excludesfile` points to `.gitignore_global`. The sibling `ignore` file is
+not the explicitly selected global ignore file. Lazygit's separate config
+also uses delta, with `--paging=never` because Lazygit handles scrolling itself.
diff --git a/home/archlinux.nix b/home/archlinux.nix
deleted file mode 100644
index 15dc488..0000000
--- a/home/archlinux.nix
+++ /dev/null
@@ -1,40 +0,0 @@
-{ pkgs, ... }:
-
-{
-  # Import common modules
-  imports = [
-    ./modules/common.nix
-    ./modules/shell.nix
-    ./modules/dev-tools.nix
-    ./modules/git.nix
-    ./modules/neovim.nix
-    ./modules/terminal.nix
-    ./modules/wezterm.nix
-    ./modules/languages.nix
-  ];
-
-  # Archlinux-specific configuration
-  # Since this is standalone Home Manager (not NixOS), we need to be careful
-  # about what services and features we enable
-
-  home = {
-    # User information - IMPORTANT: Change these before deployment
-    username = "user3301";
-    homeDirectory = "/home/user3301";
-
-    # Additional packages for Archlinux
-    packages = with pkgs; [
-      # Tools that complement Arch packages
-      # Most system packages will be installed via pacman
-      # Use Nix for development tools and user applications
-
-      # Example: Nix-specific or bleeding-edge tools
-    ];
-
-    # Home Manager state version
-    stateVersion = "25.05";
-  };
-
-  # Targets for non-NixOS systems
-  targets.genericLinux.enable = true;
-}
diff --git a/home/darwin.nix b/home/darwin.nix
deleted file mode 100644
index 10fcca5..0000000
--- a/home/darwin.nix
+++ /dev/null
@@ -1,39 +0,0 @@
-{
-  config,
-  pkgs,
-  ...
-}:
-
-{
-  # Import common modules
-  imports = [
-    ./modules/common.nix
-    ./modules/shell.nix
-    ./modules/dev-tools.nix
-    ./modules/git.nix
-    ./modules/neovim.nix
-    ./modules/terminal.nix
-    ./modules/wezterm.nix
-    ./modules/languages.nix
-  ];
-
-  home = {
-    # User information
-    username = "gaiz";
-    homeDirectory = "/Users/gaiz";
-
-    # macOS-specific packages
-    packages = with pkgs; [
-      # macOS-specific tools
-      # Note: GUI apps installed via Homebrew (see Brewfile)
-    ];
-
-    # Home Manager state version
-    stateVersion = "24.05";
-  };
-
-  # Aerospace window manager config
-  xdg.configFile."aerospace".source =
-    config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/dotfiles/aerospace/.config/aerospace";
-
-}
diff --git a/home/modules/common.nix b/home/modules/common.nix
index bbac733..1070f0b 100644
--- a/home/modules/common.nix
+++ b/home/modules/common.nix
@@ -1,7 +1,7 @@
 { config, pkgs, ... }:
 
 {
-  # Common configuration shared across all platforms
+  # Common configuration shared by the NixOS homes
 
   # Let Home Manager manage itself
   programs.home-manager.enable = true;
diff --git a/home/modules/wezterm.nix b/home/modules/wezterm.nix
index 6efac0e..4f48e63 100644
--- a/home/modules/wezterm.nix
+++ b/home/modules/wezterm.nix
@@ -2,7 +2,7 @@
 
 {
   # Wezterm terminal emulator
-  # Note: Wezterm is installed via Homebrew on macOS, via Nix on Linux
+  # Wezterm is installed in home/nixos-native.nix.
   # Not used on WSL (terminal emulator runs on the Windows host).
   xdg.configFile."wezterm".source =
     config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/dotfiles/wezterm/.config/wezterm";
diff --git a/nvim/.config/nvim/README.md b/nvim/.config/nvim/README.md
index 185280b..2a0c43d 100644
--- a/nvim/.config/nvim/README.md
+++ b/nvim/.config/nvim/README.md
@@ -1,4 +1,55 @@
-# 💤 LazyVim
+# Neovim Configuration
 
-A starter template for [LazyVim](https://github.com/LazyVim/LazyVim).
-Refer to the [documentation](https://lazyvim.github.io/installation) to get started.
+This is a customized [LazyVim](https://www.lazyvim.org/) configuration, not an
+unmodified starter. `init.lua` loads `lua/config/lazy.lua`, which bootstraps
+lazy.nvim using Git and imports LazyVim plus `lua/plugins/`.
+
+NixOS links this directory through Home Manager. On macOS and Arch Linux,
+install Neovim and its dependencies with the native package manager, then run
+`stow --target="$HOME" nvim` from `~/dotfiles`. Stow does not install Neovim.
+
+## Plugins and UI
+
+`lazyvim.json` enables Copilot Chat, mini-surround, debugging and testing
+support, and .NET, Go, and Python extras. Additional plugin configuration
+selects Catppuccin Frappe, customizes Markdown rendering and the Snacks
+dashboard/picker, and adds smear-cursor and Roslyn support. Relative line
+numbers are disabled; folding uses Tree-sitter.
+
+Plugins are installed by lazy.nvim on first launch and pinned separately in
+`lazy-lock.json`. Network access and Git are needed for installation. Use
+`:Lazy` to manage plugins and `:checkhealth` to diagnose missing dependencies.
+Review lockfile changes after plugin updates. Copilot authentication is a
+separate manual step.
+
+## Language servers
+
+`lua/plugins/lsp.lua` detects NixOS via `/etc/NIXOS` or `/etc/nixos`.
+For the explicitly configured Lua, TypeScript/web, Python (Pyright), Rust, and
+Go servers, Mason management is disabled on NixOS and enabled elsewhere.
+NixOS installs servers, formatters, compiler tools, and fswatch through
+`home/modules/neovim.nix`.
+
+The Nix server `nil` always has Mason management disabled; provide it on `PATH`
+yourself outside NixOS if you edit Nix files. Native package manifests do not
+install all language runtimes, servers, or formatters. Mason-managed tools may
+also need Node.js, Python, Go, or other runtime/build dependencies.
+
+For C#, OmniSharp is disabled in favor of `seblyng/roslyn.nvim`. On NixOS,
+`roslyn-ls` supplies `Microsoft.CodeAnalysis.LanguageServer` on `PATH`.
+Elsewhere, the additional Crashdummyy Mason registry allows:
+
+```vim
+:MasonInstall roslyn
+```
+
+Roslyn enables Neovim file watching; install `fswatch` outside NixOS as needed.
+The C# formatter override clears CSharpier so LSP formatting can be used.
+
+Python configuration looks for `venv`, `.venv`, and `.virtualenv`: Pyright uses
+a discovered Python interpreter, while pylsp can use a virtualenv's `pylsp`
+executable. Its Ruff plugin settings require that plugin to be installed in
+the chosen environment.
+
+See [LazyVim's installation requirements](https://www.lazyvim.org/installation)
+for current Neovim, compiler, and external-tool requirements.
diff --git a/nvim/.config/nvim/lua/plugins/conform.lua b/nvim/.config/nvim/lua/plugins/conform.lua
index 2c53c72..1904077 100644
--- a/nvim/.config/nvim/lua/plugins/conform.lua
+++ b/nvim/.config/nvim/lua/plugins/conform.lua
@@ -1,7 +1,7 @@
 return {
   "stevearc/conform.nvim",
   opts = function(_, opts)
-    -- Disable csharpier for C#; fall back to omnisharp's LSP formatting
+    -- Disable csharpier for C#; fall back to Roslyn's LSP formatting
     -- (lsp_format = "fallback"), which honors .editorconfig.
     opts.formatters_by_ft = opts.formatters_by_ft or {}
     opts.formatters_by_ft.cs = {}
diff --git a/systems/darwin/configuration.nix b/systems/darwin/configuration.nix
deleted file mode 100644
index 05efcae..0000000
--- a/systems/darwin/configuration.nix
+++ /dev/null
@@ -1,78 +0,0 @@
-{ pkgs, ... }:
-
-{
-  # System configuration for macOS using nix-darwin
-
-  # Nix settings
-  nix = {
-    settings = {
-      experimental-features = [
-        "nix-command"
-        "flakes"
-      ];
-      auto-optimise-store = true;
-    };
-
-    # Garbage collection
-    gc = {
-      automatic = true;
-      interval = {
-        Weekday = 0;
-        Hour = 0;
-        Minute = 0;
-      };
-      options = "--delete-older-than 7d";
-    };
-  };
-
-  # Allow unfree packages
-  nixpkgs.config.allowUnfree = true;
-
-  # System packages (minimal, most packages go in Home Manager)
-  environment.systemPackages = with pkgs; [
-    vim
-    git
-  ];
-
-  # Programs
-  programs.zsh.enable = true;
-
-  system = {
-    stateVersion = 4;
-
-    # macOS system defaults
-    defaults = {
-      dock = {
-        autohide = true;
-        orientation = "bottom";
-        show-recents = false;
-        tilesize = 48;
-      };
-
-      finder = {
-        AppleShowAllExtensions = true;
-        ShowPathbar = true;
-        FXEnableExtensionChangeWarning = false;
-      };
-
-      NSGlobalDomain = {
-        AppleShowAllExtensions = true;
-        InitialKeyRepeat = 15;
-        KeyRepeat = 2;
-      };
-    };
-  };
-
-  # Fonts
-  fonts.packages = with pkgs; [
-    (nerdfonts.override {
-      fonts = [
-        "JetBrainsMono"
-        "FiraCode"
-      ];
-    })
-  ];
-
-  # Services
-  services.nix-daemon.enable = true;
-}
diff --git a/systems/native/configuration.nix b/systems/native/configuration.nix
index 373ab6e..a7776fe 100644
--- a/systems/native/configuration.nix
+++ b/systems/native/configuration.nix
@@ -4,7 +4,7 @@
 }:
 
 {
-  # Import hardware configuration (will be generated on the target machine)
+  # Replace this VirtualBox configuration with the target machine's hardware config.
   imports = [ ../hardware/hardware-vb.nix ];
 
   # Boot loader configuration
@@ -27,7 +27,7 @@
   };
 
   # System configuration
-  system.stateVersion = "25.11"; # Update to match your NixOS version
+  system.stateVersion = "25.11"; # Compatibility defaults, not the package release
 
   # Nix settings
   nix = {
diff --git a/systems/wsl/configuration.nix b/systems/wsl/configuration.nix
index e03179e..309f0c5 100644
--- a/systems/wsl/configuration.nix
+++ b/systems/wsl/configuration.nix
@@ -15,7 +15,7 @@
   };
 
   # System configuration
-  system.stateVersion = "25.05"; # Update to match your NixOS version
+  system.stateVersion = "25.05"; # Compatibility defaults, not the package release
 
   # Nix settings
   nix = {