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.

58 declared plugins Lazy-loaded mappings No LSP format fallback 0 Luacheck warnings
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

core.lazy

Bootstraps Lazy and loads core options before plugins.

02

plugins/*

Lazy discovers specs and installs handlers for events, commands, and keys.

03

colorscheme

Catppuccin Macchiato supplies the visual baseline.

04

core.keymaps

Core editing, LSP, commands, and group labels register.

05

autocmds

Editor-level reactions attach once through named augroups.

06

highlights

Small local highlight overrides apply after the theme.

07

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.

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

Direct and unsurprising

map("n", "<leader>ca", vim.lsp.buf.code_action, {
	desc = "Code action",
})
Plugin example

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

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 },
}
Use code selectively

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 Explorer

One browser, two preserved entry mappings.

Telescope file-browserTelescope search

Search stays focused on pickers and discovery.

nvim-notifySnacks Notifier

General messages move to the plugin already loaded at startup.

none-lsConform + nvim-lint

Formatting, linting, and completion now have separate owners.

OpencodeCodeCompanion

One in-editor AI workflow remains, alongside Copilot completion.

converter modulesNative mapping APIs

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.

01stylua --check .
02luacheck .
03jq empty lazy-lock.json
04nvim --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.