core.lazy
Bootstraps Lazy and loads core options before plugins.
Neovim configuration / annotated system map
+ Small core.
Deep tools.
+ A practical map of how this Lua configuration boots, where behavior belongs, and which plugin owns each editing concern.
+ +
+
+ 01
+ Boot sequence
init.lua is intentionally boring. It establishes Lazy first, then layers presentation, mappings, editor events, highlights, and one specialized LSP helper.
+ 01
+ 02
+ 03
+ 04
+ 05
+ 06
+ 07
+
+ plugins/*
Lazy discovers specs and installs handlers for events, commands, and keys.
colorscheme
Catppuccin Macchiato supplies the visual baseline.
core.keymaps
Core editing, LSP, commands, and group labels register.
autocmds
Editor-level reactions attach once through named augroups.
highlights
Small local highlight overrides apply after the theme.
Hyprland LSP
The file-pattern-specific helper starts only where relevant.
+
+ 02
+ One owner per concern
Maintenance gets easier when two plugins do not compete for the same surface. Select a row to inspect the boundary.
+
+
+
+
+ F
+ Conformformatting
L
+ nvim-lintdiagnostics on save
C
+ nvim-cmp + LuaSnipcompletion
N
+ Snacks + Fidget + Noicethree distinct UI channels
E
+ Snacks Explorerfile browsing
T
+ ToggleTermterminal sessions
+
+ Deterministic output
+ Formatters only.
Conform runs explicit tools per filetype. Python prefers Ruff, with isort and Black as the fallback toolchain. LSP formatting is deliberately set to never, so a newly attached server cannot silently change save behavior.
Diagnostics after write
+ Lint without mutation.
nvim-lint runs once on BufWritePost. Ruff supplies Python diagnostics. Pydoclint and Codespell join only when their executables exist, avoiding noisy missing-tool warnings.
Insert-mode intelligence
+ Completion needs no shim.
nvim-cmp gathers sources and LuaSnip expands snippets. None-ls was not part of this path, so removing it does not remove completion.
Clear channel boundaries
+ Three surfaces, zero contention.
Snacks owns general notifications. Fidget owns LSP progress. Noice owns the command line and message history, with its notification forwarding and LSP progress disabled.
One tree
+ Explorer replaces two browsers.
<leader>fb and <leader>nt both open Snacks Explorer, preserving muscle memory while removing nvim-tree and Telescope file-browser.
Session-aware shells
+ Named tools stay alive.
ToggleTerm owns splits, tabs, floats, and named sessions for btop, IPython, iotop, Lazydocker, nvtop, and rmpc. Snacks Terminal remains explicitly disabled.
+
+ 03
+ Keymaps follow ownership
The configuration uses two mapping paths. The deciding question is whether the mapping requires a plugin.
+
+
+
+
+
+ Core behavior
Editing motions, workspace operations, LSP calls, and local helper commands use vim.keymap.set inside lua/core/keymaps/.
Plugin behavior
Telescope, Snacks, CodeCompanion, images, Diffview, and terminals declare mappings in their Lazy keys tables. The mapping becomes the load trigger.
+ Core example
+ Plugin example
+
+ Direct and unsurprising
map("n", "<leader>ca", vim.lsp.buf.code_action, { + desc = "Code action", +})
Mapping as load boundary
keys = {
+ { "<leader>fb", function()
+ Snacks.explorer()
+ end, desc = "File browser" },
+}which-key has one job: it labels prefix groups. It no longer converts mapping tables or acts as a second mapping registry.
+
+
+ 04
+ Lazy is the seam
Every file in lua/plugins/ returns one plugin spec. The spec keeps the trigger, dependencies, mappings, options, and exceptional setup in one navigable place.
+ Prefer data
+ Use code selectively
+
+ opts for ordinary setup
When a plugin follows require(module).setup(opts), its configuration stays declarative. Lazy can merge it and call setup at the correct time.
return { + "stevearc/conform.nvim", + opts = { -- formatter policy }, +}
config for real orchestration
ToggleTerm needs named terminal objects and a terminal-buffer autocmd. That lifecycle is real behavior, so a focused config function is justified.
config = function(_, opts) + require("toggleterm").setup(opts) + -- create named sessions once +end
Avoid eager requires: do not call plugin modules while Lua is merely building a spec table. Wrap callback references in a function so Lazy can finish registering the plugin before it loads.
+
+
+ 05
+ Complexity removed
The cleanup favors replacement over compatibility layers. Old aliases remain where useful, but dead modules and duplicate owners do not.
+
+ nvim-treeSnacks ExplorerTelescope file-browserTelescope searchnvim-notifySnacks Notifiernone-lsConform + nvim-lintOpencodeCodeCompanionconverter modulesNative mapping APIs
+ One browser, two preserved entry mappings.
Search stays focused on pickers and discovery.
General messages move to the plugin already loaded at startup.
Formatting, linting, and completion now have separate owners.
One in-editor AI workflow remains, alongside Copilot completion.
Less indirection between a key and the behavior it invokes.
+
+ 06
+ Maintenance loop
Run these from ~/.config/nvim. Each check covers a different failure class: style drift, static mistakes, or startup integration.
+
+ 01
+ stylua --check .02
+ luacheck .03
+ jq empty lazy-lock.json04
+ nvim --headless -i NONE -u ./init.lua '+qa'Tool availability: optional linters should be conditional. The configuration registers Pydoclint and Codespell only when the corresponding executable is installed.
+