diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f636876
--- /dev/null
+++ b/README.md
@@ -0,0 +1,251 @@
+# NixOS Configuration
+
+Personal NixOS system configuration using Flakes and Home Manager for declarative system management.
+
+## System Overview
+
+- **OS**: NixOS 25.11
+- **Desktop Environment**: GNOME (Wayland/X11)
+- **Terminal**: Ghostty + tmux
+- **Shell**: Zsh with Oh-My-Zsh (agnoster theme)
+- **Editor**: Neovim with [kickstart.nvim](https://github.com/0xWheatyz/kickstart.nvim)
+- **Hostname**: nixos
+
+## Features
+
+### Core System
+- **Bootloader**: GRUB with EFI support and OS Prober (dual-boot ready)
+- **Timezone**: America/New_York
+- **Locale**: en_US.UTF-8
+- **Networking**: NetworkManager enabled
+
+### Hardware Support
+- **Bluetooth**: Enabled with Blueman
+- **Fingerprint Sensor**: fprintd enabled
+- **Audio**: PipeWire with ALSA and PulseAudio compatibility
+- **Printing**: CUPS enabled
+
+### Security & Authentication
+- **YubiKey Support**: Configured for login and sudo authentication
+- **Auto-lock on YubiKey removal**: Sessions lock when YubiKey is disconnected
+- **Fingerprint Authentication**: Available for compatible hardware
+
+### Development Environment
+- **Docker**: Rootless mode enabled with proper namespace configuration
+- **VMware Workstation**: Host support enabled
+- **Nix Flakes**: Experimental features enabled
+
+### Networking
+- **Tailscale VPN**: Enabled with client routing features
+- **Firewall**: Configured with Tailscale trusted interface
+- **Editable /etc/hosts**: Permissions set to 0644 for easy modification
+
+### Desktop Customization
+- **GNOME Extensions**:
+  - Blur My Shell
+  - Just Perfection
+  - Arc Menu
+- **Fonts**: 0xProto Nerd Font, Adwaita icons
+- **Scaling**: Experimental fractional scaling and xwayland-native-scaling enabled
+- **QT Integration**: QT apps use GNOME theme (Adwaita Dark)
+
+### Alternative Window Manager
+- **Hyprland**: Configured but not currently active (see `home.nix` for configuration)
+
+## Installed Software
+
+### System Packages
+- Firefox
+- VMware Workstation
+- Lunar Client (Minecraft)
+- JetBrains Rust Rover
+- Cursor (VS Code fork)
+- Obsidian
+- Claude Code
+
+### User Packages
+- Kate (KDE text editor)
+- Bitwarden (desktop + CLI)
+- LunarVim
+- KiCad
+- Ghostty terminal
+- Python 3
+- nmap
+- minicom
+- freerdp
+
+## Configuration Files
+
+```
+.
+├── configuration.nix          # System-level configuration
+├── home.nix                   # User-level configuration (Home Manager)
+├── hardware-configuration.nix # Auto-generated hardware config
+└── flake.nix                  # Flake inputs and outputs
+```
+
+## Getting Started
+
+### First Time Setup
+
+1. Clone this repository:
+```bash
+git clone <your-repo-url> ~/Documents/nixos-configuration
+cd ~/Documents/nixos-configuration
+```
+
+2. Review and customize configurations:
+   - Edit `configuration.nix` for system-wide changes
+   - Edit `home.nix` for user-specific settings
+
+3. Apply the configuration:
+```bash
+sudo nixos-rebuild switch --flake .#nixos
+```
+
+### Making Changes
+
+#### System-Level Changes
+Edit `configuration.nix` and rebuild:
+```bash
+sudo nixos-rebuild switch --flake .#nixos
+```
+
+#### User-Level Changes
+Edit `home.nix` and rebuild:
+```bash
+sudo nixos-rebuild switch --flake .#nixos
+# or use home-manager directly:
+home-manager switch
+```
+
+### Adding Packages
+
+**System-wide** (available to all users):
+Add to `environment.systemPackages` in `configuration.nix`:
+```nix
+environment.systemPackages = with pkgs; [
+  # your-package-here
+];
+```
+
+**User-specific**:
+Add to `home.packages` in `home.nix`:
+```nix
+home.packages = with pkgs; [
+  # your-package-here
+];
+```
+
+### Updating the System
+
+Update flake inputs and rebuild:
+```bash
+nix flake update
+sudo nixos-rebuild switch --flake .#nixos
+```
+
+## Key Configurations
+
+### Git Configuration
+Managed declaratively in `home.nix`:
+- **User**: 0xWheatyz
+- **Email**: wyatt@leeworks.dev
+- **Default Branch**: master
+- **Auto push remote setup**: Enabled
+- **Custom alias**: `git lg` for pretty log visualization
+
+### SSH Configuration
+Custom SSH hosts configured in `home.nix`:
+- **vps**: Direct connection to 45.79.198.105
+- **home**: Via jump host proxy
+- **git**: Local git server at 10.0.1.10
+- Connection multiplexing enabled for faster subsequent connections
+
+### Tmux
+- Mouse support enabled
+- Window numbering starts at 1
+- 256-color terminal support
+- Auto-starts on terminal launch
+
+### Zsh
+- Oh-My-Zsh with agnoster theme
+- Custom `nix develop` wrapper that launches in zsh
+- Tmux auto-start on interactive terminals
+- Project shell indicator in prompt
+
+## Neovim Configuration
+
+Using [kickstart.nvim](https://github.com/0xWheatyz/kickstart.nvim) as the base configuration, managed through Flakes.
+
+Required dependencies are automatically installed:
+- Neovim
+- ripgrep
+- fd
+- gcc
+- gnumake
+- git
+
+Configuration is synchronized from the GitHub repository and placed in `~/.config/nvim`.
+
+## Docker Configuration
+
+Docker is configured in rootless mode:
+- Unprivileged user namespaces enabled
+- Socket variable automatically set
+- User `l-wyatt` is in the `docker` group
+
+Usage:
+```bash
+docker ps  # No sudo required
+```
+
+## Troubleshooting
+
+### Slow Shutdown
+The configuration includes optimizations for shutdown handling:
+- User manager timeout reduced to 30s (from default 90s)
+- Prevents hangs when user linger is enabled
+
+### Building from Flake
+If you encounter issues, try:
+```bash
+# Rebuild with verbose output
+sudo nixos-rebuild switch --flake .#nixos --show-trace
+
+# Check flake validity
+nix flake check
+
+# Update flake lock file
+nix flake update
+```
+
+### YubiKey Issues
+If YubiKey authentication isn't working:
+```bash
+# Check PAM configuration
+cat /etc/pam.d/login
+cat /etc/pam.d/sudo
+
+# Verify udev rules
+udevadm control --reload-rules
+```
+
+## Important Notes
+
+- **stateVersion**: Set to 25.11 - do not change after initial installation
+- **Home Manager stateVersion**: Also 25.11 - keep in sync with system version
+- **Unfree packages**: Enabled system-wide via `nixpkgs.config.allowUnfree`
+- **User groups**: l-wyatt is member of: networkmanager, wheel, docker, dialout
+- **User linger**: Enabled for background services
+
+## Additional Resources
+
+- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
+- [Home Manager Manual](https://nix-community.github.io/home-manager/)
+- [Nix Flakes](https://nixos.wiki/wiki/Flakes)
+- [kickstart.nvim Documentation](https://github.com/nvim-lua/kickstart.nvim)
+
+## License
+
+This configuration is personal and provided as-is for reference.