diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5e3543d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+# Home Manager Configuration README
+
+## Overview
+User-level package and configuration management using Home Manager. Handles development tools, shell setup, and personal applications independently from system configuration.
+
+## Structure
+```
+~/.config/home-manager/
+├── flake.nix              # Module config
+├── flake.lock             # Lockfile for flakes/modules
+└── home.nix               # Main home configuration
+```
+
+## Key Components
+
+### Development Environment
+- Node.js 24, Python 3, Bun, Deno
+- JetBrains WebStorm, Neovim
+- Docker Compose, kubectl
+- Git configuration with user details
+
+### Shell Configuration
+- Zsh with Oh My Zsh framework
+- Robbyrussell theme
+- Plugins: git, docker, kubectl
+- Custom aliases for common commands
+- Auto-completion and syntax highlighting
+
+### Applications
+- Thunderbird (email client)
+- GIMP, Inkscape (graphics)
+- Signal Desktop (messaging)
+- LibreOffice (office suite)
+- KeePassXC (password manager)
+
+### CLI Tools
+- lf (file manager)
+- ripgrep, fzf (search tools)
+- xclip (clipboard utility)
+- Google Cloud SDK
+
+## Usage
+
+Apply changes:
+```bash
+home-manager switch
+```
+
+Rollback if needed:
+```bash
+home-manager rollback
+```
+
+Check generations:
+```bash
+home-manager generations
+```
+
+## Key Aliases
+- `g` → git
+- `d` → docker
+- `k` → kubectl
+- `x` → xclip -sel clip
+- `m` → make
+- `stop` → kill processes by name
+
+## Environment Variables
+- `EDITOR` → nvim
+- `BROWSER` → firefox
+- `CYPRESS_CRASH_REPORTS` → 0
+- `JAVA_HOME` → /usr/lib/jvm/java-17-openjdk
+
+## References
+- [Home Manager Manual](https://nix-community.github.io/home-manager/)
+- [Home Manager Options](https://nix-community.github.io/home-manager/options.html)
+- [Home Manager Examples](https://github.com/nix-community/home-manager/tree/master/modules)
\ No newline at end of file