diff --git a/README.md b/README.md
new file mode 100644
index 0000000..86183c0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,81 @@
+# Absolute VIM
+
+A Lua Neovim configuration managed by [lazy.nvim](https://github.com/folke/lazy.nvim). It lives at `.config/nvim` in [absolute-dotfiles](https://github.com/boxpositron/absolute-dotfiles) as a submodule, and works on its own too.
+
+## Install
+
+Requirements: Neovim 0.12 or newer, git, a Nerd Font, `ripgrep` and `fd` for the picker, a C compiler for treesitter parsers, and optionally `lazygit` and ImageMagick (for image previews).
+
+```bash
+git clone https://github.com/boxpositron/absolute-vim ~/.config/nvim
+nvim   # lazy.nvim bootstraps itself and installs the pinned plugins from lazy-lock.json
+```
+
+Plugin versions are pinned in `lazy-lock.json`. Update them with `:Lazy update`, then commit the lockfile.
+
+## Layout
+
+```
+init.lua                  -> require("absolute")
+lua/current-theme.lua     default colorscheme
+lua/absolute/
+  core/                   options, leader, colorscheme sync and the theme registry
+  lazy.lua                lazy.nvim bootstrap; imports every spec in plugins/
+  plugins/                one plugin spec per file
+  after/                  the matching configuration, required from each spec's config
+  remap.lua               editor keymaps
+  lsp/, helpers/, utils/  extra LSP setup, project helpers, environment detection
+docs/superpowers/         design spec and plan for the 2026 modernization
+```
+
+To add a plugin, create `plugins/<name>.lua` returning its spec, and put its setup in `after/<name>.lua`.
+
+## What's inside
+
+| Area | Plugins |
+|---|---|
+| Picker, explorer, notifications, input | snacks.nvim (also `bigfile` and `quickfile`) |
+| Completion | blink.cmp with friendly-snippets; LSP, path, snippet and buffer sources, plus cmdline completion |
+| LSP and formatting | nvim-lspconfig, mason (ts_ls, lua_ls, rust_analyzer, clangd, tailwindcss, svelte, astro, biome and more), conform |
+| Syntax | nvim-treesitter, treesitter-context, treesj, tree-sitter-ghostty |
+| Git | gitsigns with current-line blame, mini.diff, lazygit in toggleterm |
+| Diagnostics and lists | trouble, todo-comments, nvim-bqf |
+| Debugging | nvim-dap and dap-ui |
+| Languages and tools | flutter-tools, venv-selector, apple-pkl, tailwind-sorter, markview, image.nvim, nvim-silicon |
+| UI | lualine, incline, indent-blankline, smear-cursor, highlight-colors, flash, mini |
+| Themes | tokyonight (default), catppuccin, rose-pine, nightfly |
+
+The 2026 modernization replaced Telescope with the snacks picker, nvim-cmp with blink.cmp, and nvim-notify and dressing with snacks, and removed abandoned and AI plugins. The spec and plan are in `docs/superpowers/`.
+
+## Themes
+
+`<leader>cs` opens a colorscheme picker. Changing the colorscheme also switches Ghostty and WezTerm to the matching theme, using the mappings in `core/theme-registry.lua`. The startup colorscheme is set in `lua/current-theme.lua`.
+
+## Keymaps
+
+The leader is Space. Highlights:
+
+| Keys | Action |
+|---|---|
+| `<C-p>` | Find files |
+| `<leader>gf` / `<leader>pr` | Git files / recent files |
+| `<leader>ps` / `<leader>sb` | Live grep / grep the word under the cursor |
+| `<leader>pf` / `<leader>cf` | File explorer at the cwd / at the current file's directory |
+| `<leader>pt` / `<leader>tt` | TODO comments in the picker / in Trouble |
+| `gd` `gi` `gt` / `<leader>cr` | Definitions, implementations, type definitions / references |
+| `K` / `<leader>gh` | Hover docs / signature help |
+| `<leader>rn` / `<leader>ca` / `<leader>f` | Rename / code actions / format |
+| `<leader>rs` | Restart LSP |
+| `<leader>td` `<leader>ts` `<leader>tq` | Trouble: diagnostics, symbols, quickfix |
+| `<leader>gs` | lazygit |
+| `<leader>db` | Toggle a breakpoint |
+| `<leader>m` | Split or join the node under the cursor (treesj) |
+| `<leader>u` | Undo tree |
+| `<leader>sr` | Replace the word under the cursor |
+| `<leader>y` / `<leader>p` | Yank to the system clipboard / paste without overwriting the register |
+| `<leader>gr` | Run a shell command in the git root |
+| `<leader>vs` | Select a Python virtualenv |
+| `<leader>sc` | Screenshot the selection with Silicon |
+| `<leader>?` | Search all keymaps |
+
+blink.cmp uses its default keymap preset: `<C-space>` opens the menu, `<C-y>` accepts, `<C-n>` and `<C-p>` move through items.