diff --git a/README.md b/README.md
index 78a198b8..1bd1f779 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,31 @@
 # nvim
 
-Personal Neovim config based on `kickstart.nvim`, with custom plugins and
-workflows for LSP, Git, and terminal-first editing.
+Personal Neovim config based on `kickstart.nvim`, tuned for backend-heavy work
+in JavaScript/TypeScript, C/C++, Kubernetes, and server development.
 
-## Quick checks
+This README is the working manual for what is configured, why it exists, and
+how to use it quickly.
 
-Use these commands after config changes:
+## Design principles
+
+- Additive, not disruptive: new plugins and mappings are added without replacing
+  existing behavior.
+- Modular plugin specs: each concern lives in `lua/custom/plugins/*.lua`.
+- Terminal-friendly workflow: most actions map to short leader sequences and
+  preserve CLI-first habits.
+- Keep startup stable: major features are lazy-loaded by command, filetype, or
+  explicit keymaps where possible.
+
+## Repository layout
+
+- `init.lua`: base options, core plugin setup, LSP, formatting, treesitter.
+- `lua/custom/plugins/*.lua`: modular plugin specs and custom behavior.
+- `doc/nvim.txt`: Vim help document (`:help nvim-config`).
+- `lazy-lock.json`: plugin lockfile managed by lazy.nvim.
+
+## Quick validation commands
+
+Run these after config changes:
 
 ```sh
 nvim --headless "+qa"
@@ -13,29 +33,176 @@ nvim --headless "+checkhealth" "+qa"
 luac -p init.lua lua/custom/**/*.lua
 ```
 
-## Git workflow keymaps
+Useful maintenance commands:
+
+```sh
+nvim --headless "+Lazy! sync" "+qa"
+nvim --headless "+MasonToolsInstallSync" "+qa"
+```
+
+## Keymap manual
+
+### Git workflow
 
 - `<leader>gg`: open Neogit UI
 - `<leader>gd`: open Diffview
 - `<leader>gD`: close Diffview
-- `<leader>gf`: file history in Diffview (current file)
-- `<leader>gF`: repository history in Diffview
-- `<leader>h...`: hunk actions from Gitsigns (`:which-key <leader>h`)
+- `<leader>gf`: Diffview file history (current file)
+- `<leader>gF`: Diffview repo history
+- `<leader>h...`: Gitsigns hunk actions (`:which-key <leader>h`)
 
-## LSP notes
+### Diagnostics and code navigation
 
-- Vue support uses `vue_ls` plus `ts_ls` scoped to `vue` filetypes.
-- `ts_ls` is wired with `@vue/typescript-plugin`, so `vue_ls` can forward
-  TypeScript requests in `.vue` buffers.
-- `typescript-tools.nvim` remains available for TypeScript/JavaScript workflows.
+- `<leader>xx`: Trouble diagnostics
+- `<leader>xw`: Trouble workspace diagnostics
+- `<leader>xd`: Trouble current buffer diagnostics
+- `<leader>xq`: Trouble quickfix list
+- `<leader>xl`: Trouble location list
+- `<leader>tc`: toggle treesitter context header
+- `<leader>jm` / `<leader>jk`: next/previous function start
+- `<leader>jM` / `<leader>jK`: next/previous function end
+- `<leader>jc` / `<leader>jC`: next/previous class start
 
-## Treesitter notes
+### Tests and debug
 
-- Uses the current API: `require('nvim-treesitter').setup()`.
-- Config installs parsers from `ensure_installed` automatically when needed.
+- `<leader>nr`: neotest run nearest
+- `<leader>nf`: neotest run current file
+- `<leader>ns`: neotest run suite (cwd)
+- `<leader>nd`: neotest debug nearest via DAP
+- `<leader>nn`: neotest summary toggle
+- `<leader>no`: neotest output for nearest test
+- `<leader>nO`: neotest output panel toggle
+- `<leader>na`: attach to running neotest process
+- `<leader>nS`: stop neotest run
+
+Existing DAP keys are unchanged:
+
+- `<F5>` continue/start, `<F1>` step into, `<F2>` step over, `<F3>` step out
+- `<F7>` toggle dap-ui, `<leader>b` toggle breakpoint, `<leader>B` conditional bp
+
+### Search, replace, and explorer
+
+- `<leader>sR`: project search/replace with grug-far
+- `<leader>eo`: open Oil explorer view (optional, non-default explorer)
+
+### CMake workflow (optional)
+
+- `<leader>cg`: CMake generate
+- `<leader>cb`: CMake build
+- `<leader>cr`: CMake run
+- `<leader>ct`: CMake test
+- `<leader>cc`: CMake select build type
+
+## Plugin stack by workflow
+
+### LSP and language intelligence
+
+- `nvim-lspconfig` + `mason-lspconfig` + `mason-tool-installer`
+- Vue integration:
+  - `vue_ls` enabled
+  - `ts_ls` scoped to `vue` with `@vue/typescript-plugin`
+  - keeps `typescript-tools.nvim` available for TS/JS workflows
+- Kubernetes/Helm integration:
+  - `yamlls` with schema mappings for Kubernetes, Helm chart, Helmfile,
+    and Kustomize
+  - `helm_ls` enabled
+  - `vim-helm` added for Helm syntax support
+
+### Treesitter and structural editing
+
+- `nvim-treesitter` uses current API (`require('nvim-treesitter').setup()`).
+- `nvim-treesitter-context` provides sticky scope context.
+- `nvim-treesitter-textobjects` adds structure-aware function/class jumps.
+
+### Debugging
+
+- Core: `nvim-dap`, `nvim-dap-ui`, `mason-nvim-dap`, `nvim-dap-go`.
+- JS/TS: `nvim-dap-vscode-js` configured with `js-debug-adapter` and
+  `pwa-node` launch/attach defaults.
+- C/C++: `codelldb` installation added through Mason DAP setup.
+
+### Testing
+
+- `neotest` core with adapters:
+  - `neotest-jest`
+  - `neotest-vitest`
+  - `neotest-gtest`
+
+Notes for C++ tests:
+
+- `neotest-gtest` needs executable mapping per project (use `:ConfigureGtest`
+  from the neotest summary window).
+
+### Formatting and linting
+
+- Formatting via `conform.nvim`:
+  - JS/TS/JSON/YAML: `prettierd` -> `prettier`
+  - C/C++: `clang_format`
+  - Lua: `stylua`
+- Linting via `nvim-lint`:
+  - markdown: `markdownlint`
+  - dockerfile: `hadolint`
+  - yaml / yaml.helm-values: `yamllint`
+
+Linting is executable-aware for configured linters to avoid noisy diagnostics
+when a linter binary is unavailable.
+
+### Project workflow plugins
+
+- `trouble.nvim`: focused diagnostics/issues panel
+- `grug-far.nvim`: project-wide search/replace
+- `oil.nvim`: optional file editing explorer (does not replace default explorer)
+- `cmake-tools.nvim`: CMake build/run/test helpers (lazy and optional)
+
+## Mason-managed tools and servers
+
+This config ensures installation for key tools used by the workflows above,
+including:
+
+- `prettierd`, `prettier`, `clang-format`
+- `hadolint`, `yamllint`, `markdownlint`, `stylua`
+- `js-debug-adapter`, `codelldb`
+- configured LSP servers from `servers` table (including `helm_ls`)
+
+Check with `:Mason` and install manually if needed.
+
+## Typical workflows
+
+### JS/TS service workflow
+
+1. Edit with LSP + treesitter context.
+2. Run nearest test with `<leader>nr` or file with `<leader>nf`.
+3. Debug test or code path with `<leader>nd` / `<F5>`.
+4. Use `<leader>sR` for safe project refactors.
+
+### C/C++ workflow
+
+1. Navigate symbols with `<leader>jm/jk/jc/jC`.
+2. Build/test with CMake mappings if project uses CMake.
+3. Debug using existing DAP keys with `codelldb` installed.
+4. Run gtest via neotest after `:ConfigureGtest` setup.
+
+### Kubernetes/Helm workflow
+
+1. Edit manifests with `yamlls` schema-backed completion/validation.
+2. Edit charts/templates with Helm support (`helm_ls`, `vim-helm`).
+3. Use `<leader>sR` for scoped multi-file YAML refactors.
+
+## Troubleshooting
+
+- Verify startup: `nvim --headless "+qa"`
+- Verify health: `nvim --headless "+checkhealth" "+qa"`
+- Verify LSP clients in current buffer: `:LspInfo`
+- Verify formatter mapping: `:ConformInfo`
+- Verify Mason state: `:Mason`
+- Re-sync plugins: `:Lazy sync`
+
+If a new feature appears missing, first confirm lazy-loading trigger
+(keymap/filetype/command) was actually used.
 
 ## Help docs
 
-This repo ships a Vim help doc. After opening Neovim, run:
+This repo ships a Vim help file:
 
 - `:help nvim-config`
+- `:help nvimn-config`