diff --git a/nvim/.config/nvim/README.md b/nvim/.config/nvim/README.md
index 2a0c43d..a2337dd 100644
--- a/nvim/.config/nvim/README.md
+++ b/nvim/.config/nvim/README.md
@@ -30,6 +30,12 @@ Go servers, Mason management is disabled on NixOS and enabled elsewhere.
 NixOS installs servers, formatters, compiler tools, and fswatch through
 `home/modules/neovim.nix`.
 
+The pinned LazyVim Go extra already enables semantic tokens during gopls
+initialization; no local override is needed. An installed plugin checkout can
+lag behind `lazy-lock.json`. If Go reports missing `textDocument` capabilities
+or semantic-token legend errors, use `:Lazy restore LazyVim` and restart Neovim
+to load the locked revision before adding capability workarounds.
+
 The Nix server `nil` always has Mason management disabled; provide it on `PATH`
 yourself outside NixOS if you edit Nix files. Native package manifests do not
 install all language runtimes, servers, or formatters. Mason-managed tools may