1 files changed, 130 insertions, 5 deletions

diff --git a/neovim/.config/nvim/README.md b/neovim/.config/nvim/README.md
index 5092af0..0e50788 100644
--- a/neovim/.config/nvim/README.md
+++ b/neovim/.config/nvim/README.md
@@ -15,6 +15,8 @@ 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
+  project_run.lua       Helper for project-local run/debug configs (see below)
+  dap_node.lua           Node/js-debug-adapter wiring for nvim-dap (see below)
   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)
@@ -34,18 +36,23 @@ such tables) and it's included on next launch.
 | 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 |
+| `statusline.lua` | lualine.nvim | Status 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 |
+| `fuzzyfinder.lua` | telescope.nvim, telescope-ui-select.nvim | Fuzzy file finder (`<C-p>`), live grep (`<leader>fg`), buffers (`<leader>fb`); also overrides `vim.ui.select` globally so overseer's/dap's pickers are Telescope windows |
+| `editing.lua` | quick-scope | `f`/`F`/`t`/`T` target highlighting (comment toggling is Neovim's built-in `gc`/`gcc`) |
+| `git.lua` | vim-fugitive, gitsigns.nvim | `: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 |
+| `toggleterm.lua` | toggleterm.nvim | Scratch terminal toggle — `<C-.>`, vertical split on the right matching claude-code.nvim's placement/ratio |
 | `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 |
+| `dap.lua` | nvim-dap, nvim-dap-ui, nvim-dap-virtual-text, mason-nvim-dap.nvim | Debugger core + UI, installs debug adapters via Mason (`<leader>d*`) |
+| `dap-python.lua` | nvim-dap-python | Python launch configs, wired to Mason's debugpy install |
+| `overseer.lua` | overseer.nvim | Save/run/rerun arbitrary run configurations for any language (`<leader>r*`) |
+| `which-key.lua` | which-key.nvim | Keymap discoverability popup; labels the `<leader>d`/`<leader>r`/etc. groups |
+| `indent-detect.lua` | guess-indent.nvim | Detects each buffer's real indentation and matches shiftwidth/tabstop to it |
 
 ## Language servers
 
@@ -59,6 +66,112 @@ 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.
 
+## Debugging
+
+Python and Node.js (JavaScript/TypeScript), via `nvim-dap` + `nvim-dap-ui`.
+The `debugpy` and `js-debug-adapter` adapters are installed and kept up to
+date by Mason (via `mason-nvim-dap.nvim`, the DAP equivalent of
+`mason-lspconfig.nvim`), so `:Mason` shows them alongside the language
+servers. Keymaps live under `<leader>d` — `<leader>db` to set a breakpoint,
+`<leader>dc` to start/continue (picks a registered config from any window,
+not just the source buffer; resumes in place if a session is already stopped
+at a breakpoint), `<leader>do`/`di`/`dO` to step over/into/out, `<leader>dt`
+to terminate, `<leader>du` to reopen the UI if you close it manually (it
+opens/closes itself automatically around a session). Press `<leader>d` and
+wait to see the full list via which-key.
+
+Python's adapter/config setup lives in `lua/plugins/dap-python.lua`, wrapping
+the `nvim-dap-python` plugin. Node's lives in `lua/config/dap_node.lua`
+instead — there's no maintained `nvim-dap-python`-style plugin for it (the
+community option, `nvim-dap-vscode-js`, expects an older, manually-built
+vscode-js-debug layout that doesn't match what Mason's `js-debug-adapter`
+package installs), so that file resolves the Mason install path directly and
+registers the `pwa-node` adapter + default `javascript`/`typescript`/
+`javascriptreact`/`typescriptreact` configs itself. It's called eagerly from
+`dap.lua`'s own `config()` rather than being its own `lua/plugins/*` entry,
+since it isn't an installable plugin — same reasoning as
+`lua/config/project_run.lua`.
+
+Adding another language later (e.g. C/C++ via `codelldb`) means adding its
+adapter to `dap.lua`'s `ensure_installed`, and either writing its own
+`dap-<language>.lua` plugin file (if a wrapper plugin exists, following the
+`dap-python.lua` pattern) or a `lua/config/dap_<language>.lua` module called
+from `dap.lua`'s `config()` (if not, following the `dap_node.lua` pattern) —
+including `lazy = false` on `dap.lua` itself either way, so the adapter is
+registered from startup rather than only after a buffer of that filetype is
+opened (the `<leader>dc` picker works from any window, so it can't rely on
+that to lazy-trigger the adapter).
+
+`overseer.lua` sets `dap = true`, which patches `nvim-dap` so a debug
+configuration can set `preLaunchTask`/`postDebugTask` to the name of an
+overseer task (or `"${defaultBuildTask}"` for whichever task is tagged
+`BUILD`) — useful for "build, then debug" workflows once a compiled
+language is added; not needed for plain Python/Node scripts.
+
+## Run configurations
+
+`overseer.nvim` provides PyCharm-style saved/rerunnable run configurations
+for any language or toolchain (shell commands, npm scripts, make, cargo,
+python scripts, ...) — it isn't tied to LSP/DAP language support. Keymaps
+live under `<leader>r` — `<leader>rr` to run a task (prompts for a template
+or a raw command), `<leader>rl` to rerun the last task, `<leader>ro` to
+toggle the task list/output window, `<leader>rq` for quick actions
+(restart/stop/dispose) on a selected task. Press `<leader>r` and wait to see
+the full list via which-key.
+
+`overseer.lua`'s `component_aliases.default` adds the `open_output`
+component (`on_start = "always"`, `focus = false`) on top of overseer's own
+defaults, so starting *any* task — custom, `.nvim.lua`-declared, or
+auto-detected (npm/make/etc.) — docks its output automatically instead of
+running silently until you manually `<leader>ro`.
+
+## Project-local run/debug configs
+
+A project can drop a `.nvim.lua` anywhere in its directory tree and have it
+auto-sourced (after a one-time `:help :trust` prompt — it runs arbitrary
+Lua, so trust it deliberately, not reflexively). This is the PyCharm-style
+"named configuration" mechanism, without adopting any other editor's file
+format.
+
+This is **not** core Vim/Neovim `'exrc'` (deliberately left off in
+options.lua) — `exrc` only checks the literal cwd once at startup, so it
+misses a project's `.nvim.lua` whenever Neovim didn't happen to start with
+cwd exactly there. Instead, an autocmd in `lua/config/autocmds.lua` searches
+*upward* from cwd on `VimEnter`/`DirChanged` (stopping at `$HOME`, same
+nearest-ancestor pattern LSP root-dir detection uses) and reads the file via
+`vim.secure.read` — the same trust mechanism `exrc` itself uses, so `:trust`
+still manages the allowlist unchanged, it's just found reliably regardless
+of how you opened Neovim.
+
+`lua/config/project_run.lua` gives that file one call per config that
+registers both a `<leader>rr` run task and a matching `<leader>dc` debug
+config from the *same* declaration, instead of repeating the command across
+two separate files:
+
+```lua
+-- <project root>/.nvim.lua
+require("config.project_run").python({
+  name = "Run app",
+  program = vim.fn.getcwd() .. "/main.py",
+  args = { "--flag" }, -- optional, shared by both run and debug
+})
+
+require("config.project_run").node({
+  name = "Run app",
+  program = vim.fn.getcwd() .. "/index.js", -- or npmScript = "dev" for `npm run dev`
+  args = { "--flag" }, -- optional, shared by both run and debug
+})
+```
+
+`dap.lua` and `overseer.lua` are both `lazy = false` specifically so this
+works immediately when the autocmd sources the file, rather than needing
+the plugins already triggered by a keymap first.
+
+(`nvim-dap` and `overseer.nvim` also natively read `.vscode/launch.json` and
+`.vscode/tasks.json` respectively, if you'd rather use that ecosystem's
+format for some reason — but `project_run.lua` is the recommended path here
+since it states each command once.)
+
 ## Adding a new plugin
 
 Drop a new file in `lua/plugins/` (or add to an existing group file if it
@@ -74,6 +187,18 @@ return {
 Restart Neovim (or `:Lazy sync`) to install it, then commit the updated
 `lazy-lock.json` alongside your change.
 
+If a plugin backs a keymap or command meant to work from any window — not
+scoped to a particular filetype/buffer, like the run/debug pickers, the
+fuzzy finder, or the file explorer — set `lazy = false` rather than gating
+it behind `ft`/`event`, even though lazy.nvim would otherwise recommend one.
+A trigger tied to "some buffer of type X was opened" silently breaks the
+moment the keymap fires before that's happened (this bit `dap-python.lua`:
+it lazy-loaded on `ft = "python"`, so debugging broke whenever `<leader>dc`
+was pressed before any `.py` buffer had been opened this session). Plain
+per-buffer editing conveniences (`autopairs.lua`'s `InsertEnter`,
+`ale.lua`'s `BufReadPre`, `which-key.lua`'s `VeryLazy`) don't have this
+problem and can stay lazy.
+
 ## Relationship to Vim
 
 Vim and Neovim used to share one `vimrc` (`has('nvim')` branches handled the