docs(nvim): record why this is hand-rolled, not a distro

State the reason for nixvim over LazyVim/NvChad — lazy.nvim fetches and updates
plugins at runtime, putting the editor outside the flake — along with what that
costs in ergonomics, and that borrowing a distro's keymaps and defaults into
this file remains open.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015D4NsszUG7hy9ghKZ4nfhm

modules/nvim.nix

@@ -1,8 +1,26 @@
 # Neovim, configured declaratively via nixvim. The editor — plugins, LSP,
 # completion, keymaps — is defined here and pinned by the flake lock; nothing is
-# downloaded at runtime, unlike an imperative distro (NvChad/LazyVim). The nixvim
+# downloaded at runtime. The nixvim home-manager module that provides
-# home-manager module that provides `programs.nixvim` is imported for consumers by
+# `programs.nixvim` is imported for consumers by `homeModules.default` in
-# `homeModules.default` in flake.nix, so this file only sets options.
+# flake.nix, so this file only sets options.
+#
+# Why this rather than a distro (LazyVim, NvChad, AstroNvim): those drive
+# lazy.nvim as a package manager, which git-clones plugins into
+# ~/.local/share/nvim on first launch and updates them in place. The editor's
+# actual contents would then live outside the flake — unpinned, unreproducible,
+# and invisible to a rollback.
+#
+# That choice has a price, and it is paid in ergonomics. A distro ships hundreds
+# of defaults other people already sanded smooth; this config does not. Rough
+# edges surface one at a time, mid-task, and each gets fixed by hand here (see
+# the `<leader>bd` and `<leader>Q` keymaps for two such fixes). Anyone extending
+# this should expect that cost rather than be surprised by it.
+#
+# The middle path stays open: the objection is to lazy.nvim as a *runtime*
+# package manager, not to a distro's ergonomics. Individual keymaps, option
+# sets, and plugin configurations can be lifted from LazyVim & co. into this
+# file, and nixvim installs any plugin set declaratively. Borrow freely — just
+# keep the installation declarative.
 #
 # Consumer knobs (the option-with-default contract): `local.nvim.enable` to opt
 # out wholesale, `local.nvim.colorscheme` to swap theme in one line, and