diff --git a/README.md b/README.md
index e69de29b..6485f38a 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,82 @@
+# 🌌 Whipsmart.nvim
+
+Whipsmart.nvim is a modular, native-first Neovim configuration built on top of the Neovim 0.12+ `vim.pack` system. It evolved from [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim) into a modular, machine-aware "Grand Unified" configuration.
+
+## ✨ Features
+
+- **Modular Architecture**: Plugin configurations are isolated in `lua/plugins/*.lua`.
+- **Native-First**: Leverages Neovim 0.12's built-in `vim.pack` for plugin management and native LSP/Autocomplete improvements.
+- **Ergonomic Dashboard**: Includes `pack-manager.nvim` to provide a polished, Lazy-like UI on top of native primitives.
+- **Machine Awareness**: Built-in hostname detection in `init.lua` for machine-specific overrides.
+- **Version Pinning**: Uses `nvim-pack-lock.json` for reproducible environments across all your hardware.
+
+## 🚀 Quick Start
+
+### 1. Prerequisites
+
+Ensure you are running **Neovim 0.12+** (nightly or latest stable). You will also need:
+- `git`, `make`, `unzip`, `gcc`
+- [ripgrep](https://github.com/BurntSushi/ripgrep) and [fd](https://github.com/sharkdp/fd)
+- A [Nerd Font](https://www.nerdfonts.com/) (recommended)
+
+### 2. Installation
+
+```sh
+# Clone your fork (replace <your_username> with your GitHub handle)
+git clone https://github.com/<your_username>/whipsmart.nvim.git ~/.config/nvim
+
+# Start Neovim
+nvim
+```
+
+## 🛠️ Package Management
+
+Whipsmart provides two ways to manage your plugins:
+
+### The "Lazy" Way (High-Level UI)
+Press **`<leader>pm`** to open the **Package Manager Menu**. This dashboard allows you to:
+- Check for updates
+- Install new plugins
+- Disable/Enable existing plugins
+- Clean up unused packages
+
+### The "Native" Way (Low-Level Access)
+Whipsmart also exposes the raw `vim.pack` primitives:
+- **`<leader>ps`**: **Sync** (Triggers `vim.pack.update()` to fetch new metadata).
+- **`<leader>pi`**: **Inspect** (View current plugin status offline).
+- **`:w`**: Inside the update buffer, write to disk to apply changes.
+
+## 🏗️ Project Layout
+
+```text
+~/.config/nvim/
+├── init.lua                # Core options, keymaps, and modular loader
+├── UNIFIED.md              # The Grand Unified roadmap and local instructions
+├── nvim-pack-lock.json     # Plugin lockfile (Tracked in Git)
+└── lua/
+    └── plugins/            # Individual plugin modules
+        ├── core_ui.lua     # Which-key, Colorscheme, Oil, Mini.nvim
+        ├── lsp.lua         # LSP, Mason, and Tooling
+        ├── telescope.lua   # Fuzzy Finding
+        ├── cmp.lua         # Autocompletion and Snippets
+        ├── treesitter.lua  # Syntax Highlighting
+        ├── format.lua      # Conform.nvim Formatting
+        └── pack_manager.lua # pack-manager.nvim UI setup
+```
+
+## 💻 Customization
+
+### Adding a New Plugin
+To add a plugin, create a new `.lua` file in `lua/plugins/`. Whipsmart will automatically detect and load it.
+
+Example `lua/plugins/harpoon.lua`:
+```lua
+vim.pack.add({ "https://github.com/ThePrimeagen/harpoon" })
+-- Your configuration here
+```
+
+### Machine-Specific Settings
+Whipsmart uses hostname detection. Open `init.lua` and locate the **Machine Specific Setup** section to add overrides for your specific hardware.
+
+## 📜 Credits
+Whipsmart started as a fork of [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim) and maintains its spirit of being a starting point rather than a distribution.
diff --git a/nvim-pack-lock.json b/nvim-pack-lock.json
index 436033f1..3dc8a35b 100644
--- a/nvim-pack-lock.json
+++ b/nvim-pack-lock.json
@@ -59,6 +59,10 @@
       "rev": "0fcc83805ad11cf714a949c98c605ed717e0b83e",
       "src": "https://github.com/stevearc/oil.nvim"
     },
+    "pack-manager.nvim": {
+      "rev": "e947437ab03c2e20d7eb4e27d1a5f043a9ab1d72",
+      "src": "https://github.com/mplusp/pack-manager.nvim"
+    },
     "plenary.nvim": {
       "rev": "74b06c6c75e4eeb3108ec01852001636d85a932b",
       "src": "https://github.com/nvim-lua/plenary.nvim"