Add README to the Neovim config

Documents the file/folder layout, what each lua/plugins/*.lua group
contains, the managed language servers, how to add a new plugin, and
the (now fully independent) relationship to Vim's own vimrc.

1 files changed, 83 insertions, 0 deletions

diff --git a/neovim/.config/nvim/README.md b/neovim/.config/nvim/README.md
new file mode 100644
index 0000000..5092af0
--- /dev/null
+++ b/neovim/.config/nvim/README.md
@@ -0,0 +1,83 @@
+# Neovim config
+
+Standalone, Neovim-only Lua config — independent of `../../vim/.vim/vimrc`
+(Vim's own config; it is not read by Neovim at all). Plugin manager is
+[lazy.nvim](https://github.com/folke/lazy.nvim), which bootstraps itself on
+first launch — no submodule needed.
+
+## Layout
+
+```
+init.lua              Entry point: sets <leader>, then loads config/* in order
+ftplugin/
+  python.lua           Per-filetype settings for *.py (tabstop/shiftwidth/etc.)
+lua/config/            Everything that isn't a plugin declaration
+  options.lua           vim.opt settings (search, undo, whitespace display, ...)
+  keymaps.lua           Global keymaps not owned by a specific plugin
+  autocmds.lua          Global autocmds not owned by a specific plugin
+  lazy.lua              Bootstraps lazy.nvim and points it at lua/plugins/
+lua/plugins/            One file per plugin (or small plugin group), each
+                        returning a lazy.nvim plugin spec (or list of specs)
+lazy-lock.json          Plugin versions pinned by lazy.nvim - commit changes
+                        to this whenever plugins are added/updated
+.gitignore              Ignores spell/ (spellfile downloads)
+```
+
+`lua/config/*` and `lua/plugins/*` are auto-loaded: `init.lua` does
+`require("config.lazy")`, which calls `require("lazy").setup("plugins", ...)`
+— lazy.nvim automatically picks up every file under `lua/plugins/`, so a new
+file dropped there just needs to `return { "author/repo", ... }` (or a list of
+such tables) and it's included on next launch.
+
+## What's in `lua/plugins/`
+
+| File | Plugin(s) | Purpose |
+|---|---|---|
+| `colorscheme.lua` | vim-janah | Color scheme, falls back to `desert` if it fails to load |
+| `statusline.lua` | vim-airline, vim-airline-themes, tmuxline.vim | Status/tab line |
+| `filetree.lua` | neo-tree.nvim | File explorer sidebar with git-status colors (`<leader>e` to toggle) |
+| `fuzzyfinder.lua` | ctrlp.vim | Fuzzy file finder (ripgrep-backed if `rg` is on PATH) |
+| `editing.lua` | nerdcommenter, quick-scope | Comment toggling, `f`/`F`/`t`/`T` target highlighting |
+| `git.lua` | vim-fugitive, vim-signify | `:Git` commands, git-diff gutter signs |
+| `ale.lua` | ALE | Linters/fixers only — `g:ale_disable_lsp = 1` so it doesn't fight the LSP client's diagnostics/hover/go-to-def |
+| `langs.lua` | vim-ansible-yaml, vim-terraform | Only loaded if `ansible`/`terraform` is on PATH (lazy.nvim `cond`) |
+| `claude-code.lua` | claude-code.nvim (+ plenary.nvim) | `:ClaudeCode` and friends |
+| `treesitter.lua` | nvim-treesitter (`main` branch) | Parser installs + syntax highlighting |
+| `autopairs.lua` | nvim-autopairs, nvim-ts-autotag | Auto-close brackets/quotes/HTML+JSX tags |
+| `completion.lua` | blink.cmp (+ friendly-snippets) | Completion popup, Tab-to-accept (`super-tab` preset) |
+| `lsp.lua` | nvim-lspconfig, mason.nvim, mason-lspconfig.nvim | Installs & enables language servers, wires blink.cmp's capabilities into them |
+
+## Language servers
+
+Managed by Mason, auto-installed via `lua/plugins/lsp.lua`'s
+`ensure_installed`: `pyright`, `lua_ls`, `bashls`, `terraformls`, `yamlls`,
+`ts_ls`, `cssls`, `html`. `clangd` is enabled separately (not
+Mason-installed) since it already ships with Xcode Command Line Tools.
+
+Refactoring/navigation (rename, code actions, references, go-to-definition,
+hover) come from Neovim's built-in default LSP keymaps (`:help lsp-defaults`)
+once a server attaches — `grn`, `gra`, `grr`, `gri`, `gO`, `K`, `<C-]>`. No
+extra plugin or keymap needed for these.
+
+## Adding a new plugin
+
+Drop a new file in `lua/plugins/` (or add to an existing group file if it
+belongs there) returning a lazy.nvim spec, e.g.:
+
+```lua
+return {
+  "author/plugin-name",
+  opts = {},
+}
+```
+
+Restart Neovim (or `:Lazy sync`) to install it, then commit the updated
+`lazy-lock.json` alongside your change.
+
+## Relationship to Vim
+
+Vim and Neovim used to share one `vimrc` (`has('nvim')` branches handled the
+differences). They're now fully independent: Vim keeps `../../vim/.vim/vimrc`
+with its own plugin manager (vim-plug) and completion (YouCompleteMe +
+jedi-vim); nothing under this directory affects Vim, and nothing in
+`vim/.vim` affects Neovim.