diff --git a/README.md b/README.md
index 185280b..f1996f0 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,76 @@
-# 💤 LazyVim
+# nvim config
 
-A starter template for [LazyVim](https://github.com/LazyVim/LazyVim).
-Refer to the [documentation](https://lazyvim.github.io/installation) to get started.
+Personal Neovim config built on [LazyVim](https://www.lazyvim.org/).
+
+## Requirements
+
+- Neovim >= 0.9
+- Git
+- A [Nerd Font](https://www.nerdfonts.com/) (optional, for icons)
+- A terminal with true color support
+
+## Fresh install on a new machine
+
+**1. Back up any existing config**
+
+```bash
+mv ~/.config/nvim ~/.config/nvim.bak
+mv ~/.local/share/nvim ~/.local/share/nvim.bak
+```
+
+**2. Clone this repo**
+
+```bash
+git clone git@github.com:yourusername/nvim-config.git ~/.config/nvim
+```
+
+**3. Open Neovim**
+
+```bash
+nvim
+```
+
+Lazy.nvim will bootstrap itself and install all plugins automatically. Wait for it to finish, then restart nvim.
+
+---
+
+## Syncing changes from another machine
+
+```bash
+cd ~/.config/nvim
+git pull
+```
+
+Then inside nvim, run:
+
+```
+:Lazy sync
+```
+
+This installs/removes/updates plugins to match `lazy-lock.json`.
+
+---
+
+## Repo structure
+
+```
+~/.config/nvim/
+├── init.lua              # Entry point
+├── lazy-lock.json        # Pinned plugin versions
+└── lua/
+    ├── config/
+    │   ├── autocmds.lua  # Custom autocommands
+    │   ├── keymaps.lua   # Custom keymaps
+    │   └── options.lua   # Neovim options
+    └── plugins/          # Plugin specs & overrides
+```
+
+## Useful commands
+
+| Command        | Description                          |
+| -------------- | ------------------------------------ |
+| `:Lazy`        | Open plugin manager UI               |
+| `:Lazy sync`   | Sync plugins to lock file            |
+| `:Lazy update` | Update all plugins & write lock file |
+| `:LazyHealth`  | Check for issues                     |
+| `:checkhealth` | General Neovim health check          |