thing

init.lua

@@ -1,7 +1,16 @@
 --[[
-  Neovim entrypoint: `lua/kickstart/init.lua` sets options, keymaps, autocommands,
-  diagnostics, then bootstraps lazy.nvim and loads `kickstart.plugins.spec`.
-  Kickstart’s long banner lived here originally; see upstream kickstart.nvim README if you want it back.
+  Path: init.lua (Neovim config root)
+  Module: none — Neovim executes this file before any Lua `require`.
+
+  Purpose
+    Single entrypoint for your configuration. Everything else lives under
+    `lua/` so this file stays small and easy to skim.
+
+  Rationale
+    A minimal root `init.lua` avoids duplicating logic that belongs in modular
+    Lua modules and matches common Neovim + lazy.nvim layouts.
+
+  See `:help config` and `:help lua-require`.
 ]]
 
-require 'kickstart'
+require 'plugins.kickstart'

lua/custom/git_links.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/custom/git_links.lua
+  Module: custom.git_links
+
+  Purpose
+    Opens the current buffer’s file on GitHub (or compatible origin) in the
+    browser, including a line or range anchor from Normal or Visual mode.
+
+  Rationale
+    Small, focused utility used by `plugins.kickstart.keymaps` (`<leader>go`).
+    Kept under `custom/` so it stays clearly “yours” vs. generated plugin specs.
+
+  Dependencies: git(1), xdg-open (Linux); file must be tracked by git.
+]]
+
 local M = {}
 
 M.open_github = function()

lua/custom/plugins/init.lua

@@ -1,4 +1,18 @@
--- Add plugins here (neo-tree lives in `lua/kickstart/plugins/neo-tree.lua`).
+--[[
+  Path: lua/custom/plugins/init.lua
+  Module: custom.plugins
+
+  Purpose
+    Lazy.nvim specs for plugins that are not part of the main `plugins.kickstart`
+    tree (e.g. HTTP client, experimental additions).
+
+  Rationale
+    `plugins.kickstart.plugins.spec` appends this module last so your personal
+    plugins stay merge-friendly and easy to find. Neo-tree and core stack live
+    under `plugins.kickstart.plugins` instead.
+
+  See `:help lazy.nvim-plugin-spec`.
+]]
 
 ---@module 'lazy'
 ---@type LazySpec

lua/kickstart/autocmds.lua

@@ -1,13 +0,0 @@
-vim.api.nvim_create_autocmd('TextYankPost', {
-  desc = 'Highlight when yanking (copying) text',
-  group = vim.api.nvim_create_augroup('kickstart-highlight-yank', { clear = true }),
-  callback = function() vim.hl.on_yank() end,
-})
-
-vim.api.nvim_create_autocmd('FileType', {
-  group = vim.api.nvim_create_augroup('kickstart-markdown-safe-read', { clear = true }),
-  pattern = 'markdown',
-  callback = function()
-    vim.opt_local.modeline = false
-  end,
-})

lua/kickstart/init.lua

@@ -1,10 +0,0 @@
-vim.g.mapleader = ' '
-vim.g.maplocalleader = ' '
-
-vim.g.have_nerd_font = true
-
-require 'kickstart.options'
-require 'kickstart.keymaps'
-require 'kickstart.autocmds'
-require 'kickstart.diagnostics'
-require 'kickstart.lazy'

lua/kickstart/plugins/autopairs.lua

@@ -1,10 +0,0 @@
--- autopairs
--- https://github.com/windwp/nvim-autopairs
-
----@module 'lazy'
----@type LazySpec
-return {
-  'windwp/nvim-autopairs',
-  event = 'InsertEnter',
-  opts = {},
-}

lua/kickstart/plugins/guess_indent.lua

@@ -1,4 +0,0 @@
----@type LazySpec
-return {
-  { 'NMAC427/guess-indent.nvim', opts = {} },
-}

lua/kickstart/plugins/indent_line.lua

@@ -1,13 +0,0 @@
--- Add indentation guides even on blank lines
-
----@module 'lazy'
----@type LazySpec
-return {
-  'lukas-reineke/indent-blankline.nvim',
-  -- Enable `lukas-reineke/indent-blankline.nvim`
-  -- See `:help ibl`
-  main = 'ibl',
-  ---@module 'ibl'
-  ---@type ibl.config
-  opts = {},
-}

lua/kickstart/plugins/mini_icons.lua

@@ -1,14 +0,0 @@
----@type LazySpec
-return {
-{
-  'nvim-mini/mini.icons',
-  opts = {
-    file = {
-      ['.go-version'] = { glyph = '', hl = 'MiniIconsBlue' },
-    },
-    filetype = {
-      gotmpl = { glyph = '󰟓', hl = 'MiniIconsGrey' },
-    },
-  },
-},
-}

lua/kickstart/plugins/neotest_golang.lua

@@ -1,6 +0,0 @@
----@type LazySpec
-return {
-{
-  'fredrikaverpil/neotest-golang',
-},
-}

lua/kickstart/plugins/render_markdown.lua

@@ -1,12 +0,0 @@
----@type LazySpec
-return {
-{
-  'MeanderingProgrammer/render-markdown.nvim',
-  dependencies = { 'nvim-treesitter/nvim-treesitter', 'nvim-mini/mini.nvim' },
-  ft = { 'markdown', 'markdown.mdx' },
-  opts = {
-    latex = { enabled = false },
-    completions = { lsp = { enabled = true }, blink = { enabled = true } },
-  },
-},
-}

lua/kickstart/plugins/spec.lua

@@ -1,43 +0,0 @@
----@param out table
----@param chunk LazySpec|LazySpec[]
-local function append_specs(out, chunk)
-  if type(chunk[1]) == 'string' then
-    out[#out + 1] = chunk
-    return
-  end
-  for i = 1, #chunk do
-    out[#out + 1] = chunk[i]
-  end
-end
-
----@type LazySpec
-local specs = {}
-local mods = {
-  'kickstart.plugins.guess_indent',
-  'kickstart.plugins.gitsigns',
-  'kickstart.plugins.which_key',
-  'kickstart.plugins.render_markdown',
-  'kickstart.plugins.telescope',
-  'kickstart.plugins.lsp',
-  'kickstart.plugins.conform',
-  'kickstart.plugins.blink',
-  'kickstart.plugins.tokyonight',
-  'kickstart.plugins.todo_comments',
-  'kickstart.plugins.mini',
-  'kickstart.plugins.treesitter',
-  'kickstart.plugins.vim_helm',
-  'kickstart.plugins.neotest_golang',
-  'kickstart.plugins.mini_icons',
-  'kickstart.plugins.debug',
-  'kickstart.plugins.indent_line',
-  'kickstart.plugins.lint',
-  'kickstart.plugins.autopairs',
-  'kickstart.plugins.neo-tree',
-  'custom.plugins',
-}
-
-for _, mod in ipairs(mods) do
-  append_specs(specs, require(mod))
-end
-
-return specs

lua/kickstart/plugins/todo_comments.lua

@@ -1,13 +0,0 @@
----@type LazySpec
-return {
--- Highlight todo, notes, etc in comments
-{
-  'folke/todo-comments.nvim',
-  event = 'VimEnter',
-  dependencies = { 'nvim-lua/plenary.nvim' },
-  ---@module 'todo-comments'
-  ---@type TodoOptions
-  ---@diagnostic disable-next-line: missing-fields
-  opts = { signs = false },
-},
-}

lua/kickstart/plugins/vim_helm.lua

@@ -1,11 +0,0 @@
----@type LazySpec
-return {
-{
-  'towolf/vim-helm',
-  event = 'BufReadPre',
-  config = function()
-    -- This plugin automatically detects helm files (including .tpl)
-    -- and sets the filetype to "helm" instead of "yaml"
-  end,
-},
-}

lua/plugins/kickstart/autocmds.lua

@@ -0,0 +1,28 @@
+--[[
+  Path: lua/plugins/kickstart/autocmds.lua
+  Module: plugins.kickstart.autocmds
+
+  Purpose
+    Small, global autocommand hooks: yank highlight feedback and safer defaults
+    for Markdown buffers (modelines off in untrusted README-style files).
+
+  Rationale
+    Autocommands belong next to options/keymaps so “editor shell” behavior is
+    grouped separately from per-plugin `config = function()` blocks.
+
+  See `:help autocmd`, `:help vim.hl.on_yank()`, `:help 'modeline'`.
+]]
+
+vim.api.nvim_create_autocmd('TextYankPost', {
+  desc = 'Highlight when yanking (copying) text',
+  group = vim.api.nvim_create_augroup('kickstart-highlight-yank', { clear = true }),
+  callback = function() vim.hl.on_yank() end,
+})
+
+vim.api.nvim_create_autocmd('FileType', {
+  group = vim.api.nvim_create_augroup('kickstart-markdown-safe-read', { clear = true }),
+  pattern = 'markdown',
+  callback = function()
+    vim.opt_local.modeline = false
+  end,
+})

lua/plugins/kickstart/diagnostics.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/plugins/kickstart/diagnostics.lua
+  Module: plugins.kickstart.diagnostics
+
+  Purpose
+    One global `vim.diagnostic.config` for how LSP diagnostics render: signs,
+    virtual text, floating previews, underline, and sort order.
+
+  Rationale
+    A single module avoids conflicting `vim.diagnostic.config` calls (e.g. one
+    at startup and another inside LSP setup) overwriting each other.
+
+  See `:help vim.diagnostic.config()`, `:help diagnostic-signs`.
+]]
+
 vim.diagnostic.config {
   severity_sort = true,
   float = { border = 'rounded', source = 'if_many' },

lua/plugins/kickstart/health.lua

@@ -1,9 +1,17 @@
 --[[
---
--- This file is not required for your own configuration,
--- but helps people determine if their system is setup correctly.
---
---]]
+  Path: lua/plugins/kickstart/health.lua
+  Module: plugins.kickstart.health
+
+  Purpose
+    Optional `:checkhealth` provider: Neovim version gate, common CLI tools
+    (git, make, unzip, rg), and contextual notes for Mason-related warnings.
+
+  Rationale
+    Health checks catch environment issues before debugging “mystery” plugin
+    failures. Safe to ignore if you do not run `:checkhealth`; harmless if loaded.
+
+  See `:help health-dev`, `:checkhealth`.
+]]
 
 local check_version = function()
   local verstr = tostring(vim.version())
@@ -20,7 +28,6 @@ local check_version = function()
 end
 
 local check_external_reqs = function()
-  -- Basic utils: `git`, `make`, `unzip`
   for _, exe in ipairs { 'git', 'make', 'unzip', 'rg' } do
     local is_executable = vim.fn.executable(exe) == 1
     if is_executable then

lua/plugins/kickstart/init.lua

@@ -0,0 +1,27 @@
+--[[
+  Path: lua/plugins/kickstart/init.lua
+  Module: plugins.kickstart
+
+  Purpose
+    Orchestrates core editor setup: globals, options, keymaps, autocommands,
+    diagnostics, then installs and loads third-party plugins via lazy.nvim.
+
+  Load order
+    1. Leader keys and UI flags must be set before lazy.nvim (plugin keymaps).
+    2. Options, keymaps, autocommands, and diagnostics run before plugins so
+       baseline behavior exists even if a plugin fails to load.
+    3. `lazy.lua` runs last and pulls in the full Lazy plugin spec list.
+
+  See `:help mapleader`, `:help vim.g`, `:help lazy.nvim.txt`.
+]]
+
+vim.g.mapleader = ' '
+vim.g.maplocalleader = ' '
+
+vim.g.have_nerd_font = true
+
+require 'plugins.kickstart.options'
+require 'plugins.kickstart.keymaps'
+require 'plugins.kickstart.autocmds'
+require 'plugins.kickstart.diagnostics'
+require 'plugins.kickstart.lazy'

lua/plugins/kickstart/keymaps.lua

@@ -1,3 +1,19 @@
+--[[
+  Path: lua/plugins/kickstart/keymaps.lua
+  Module: plugins.kickstart.keymaps
+
+  Purpose
+    Non-plugin (or minimally coupled) normal-mode maps: search, diagnostics
+    quickfix, terminal escape, window navigation, GitHub “open in browser,”
+    Neo-tree toggles, and visual paste without clobbering a register.
+
+  Rationale
+    Keeping these maps here avoids scattering `vim.keymap.set` across plugin
+    config files and ensures they exist even before lazy.nvim finishes loading.
+
+  See `:help vim.keymap.set()`, `:help diagnostic-loclist`.
+]]
+
 vim.keymap.set('n', '<Esc>', '<cmd>nohlsearch<CR>')
 
 vim.keymap.set('n', '<leader>q', vim.diagnostic.setloclist, { desc = 'Open diagnostic [Q]uickfix list' })

lua/plugins/kickstart/lazy.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/plugins/kickstart/lazy.lua
+  Module: plugins.kickstart.lazy
+
+  Purpose
+    Bootstraps folke/lazy.nvim if missing, prepends it to runtimepath, and calls
+    `lazy.setup()` with the aggregated plugin specification plus UI icon prefs.
+
+  Rationale
+    lazy.nvim must be on `runtimepath` before `require('lazy')`. Keeping clone +
+    setup here isolates plugin-manager mechanics from editor options/keymaps.
+
+  See `:help lazy.nvim.txt`, `:help rtp`.
+]]
+
 local lazypath = vim.fn.stdpath 'data' .. '/lazy/lazy.nvim'
 if not (vim.uv or vim.loop).fs_stat(lazypath) then
   local lazyrepo = 'https://github.com/folke/lazy.nvim.git'
@@ -9,7 +24,7 @@ end
 local rtp = vim.opt.rtp
 rtp:prepend(lazypath)
 
-require('lazy').setup(require 'kickstart.plugins.spec', {
+require('lazy').setup(require 'plugins.kickstart.plugins.spec', {
   ui = {
     icons = vim.g.have_nerd_font and {} or {
       cmd = '⌘',

lua/plugins/kickstart/options.lua

@@ -1,4 +1,17 @@
--- Options: see `:help vim.o` and `:help option-list`
+--[[
+  Path: lua/plugins/kickstart/options.lua
+  Module: plugins.kickstart.options
+
+  Purpose
+    Sets buffer-agnostic Neovim options (`vim.o` / `vim.opt`): editing feel,
+    UI chrome, search, splits, and persistence (e.g. undofile).
+
+  Rationale
+    Centralizing options keeps behavior predictable and documents defaults in
+    one place. Clipboard is scheduled after UI enter to avoid slowing startup.
+
+  See `:help vim.o`, `:help option-list`, `:help 'clipboard'`.
+]]
 
 vim.o.number = true
 

lua/plugins/kickstart/plugins/autopairs.lua

@@ -0,0 +1,22 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/autopairs.lua
+  Module: plugins.kickstart.plugins.autopairs
+
+  Purpose
+    Lazy spec for nvim-autopairs: inserts/closes paired brackets and quotes in
+    Insert mode; integrates cleanly with completion when configured.
+
+  Rationale
+    Loaded on `InsertEnter` so startup stays fast. Empty `opts` uses plugin
+    defaults; customize here if you need rule exceptions or cmp integration.
+
+  See https://github.com/windwp/nvim-autopairs
+]]
+
+---@module 'lazy'
+---@type LazySpec
+return {
+  'windwp/nvim-autopairs',
+  event = 'InsertEnter',
+  opts = {},
+}

lua/plugins/kickstart/plugins/blink.lua

@@ -1,3 +1,19 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/blink.lua
+  Module: plugins.kickstart.plugins.blink
+
+  Purpose
+    Lazy spec for saghen/blink.cmp: completion menu, LSP source, snippets via
+    LuaSnip, signature help, and keymap preset (`super-tab`).
+
+  Rationale
+    Standalone entry complements the `blink.cmp` dependency pinned under
+    `lsp.lua` so capabilities exist before servers start; lazy merges duplicate
+    plugin IDs by version.
+
+  See `:help blink.cmp`.
+]]
+
 ---@type LazySpec
 return {
 { -- Autocompletion

lua/plugins/kickstart/plugins/conform.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/conform.lua
+  Module: plugins.kickstart.plugins.conform
+
+  Purpose
+    Lazy spec for conform.nvim: formatter orchestration (`<leader>f`), per-FT
+    formatter lists (stylua, sql_formatter, prettier), and format-on-save policy.
+
+  Rationale
+    Keeps formatting separate from LSP where you explicitly disable or gate LSP
+    format fallback per filetype.
+
+  See `:help conform.nvim`.
+]]
+
 ---@type LazySpec
 return {
 { -- Autoformat

lua/plugins/kickstart/plugins/debug.lua

@@ -1,10 +1,17 @@
--- debug.lua
---
--- Shows how to use the DAP plugin to debug your code.
---
--- Primarily focused on configuring the debugger for Go, but can
--- be extended to other languages as well. That's why it's called
--- kickstart.nvim and not kitchen-sink.nvim ;)
+--[[
+  Path: lua/plugins/kickstart/plugins/debug.lua
+  Module: plugins.kickstart.plugins.debug
+
+  Purpose
+    Lazy spec for nvim-dap + nvim-dap-ui + mason-nvim-dap + nvim-dap-go: debug
+    sessions, UI controls, breakpoint signs, and Go/Delve configurations.
+
+  Rationale
+    Debugging is optional but heavy; isolating DAP keeps optional tooling out of
+    LSP startup. Extend `dap.configurations` for other languages as needed.
+
+  See `:help dap.txt`, plugin READMEs.
+]]
 
 ---@module 'lazy'
 ---@type LazySpec

lua/plugins/kickstart/plugins/gitsigns.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/gitsigns.lua
+  Module: plugins.kickstart.plugins.gitsigns
+
+  Purpose
+    Lazy spec for lewis6991/gitsigns.nvim: gutter hunks, stage/reset, blame,
+    diff against index / HEAD / default branch, and buffer-local keymaps.
+
+  Rationale
+    Single source of truth for Git-in-editor UX; pairs with which-key groups
+    under `<leader>h` and avoids duplicating gitsigns setup in `init.lua`.
+
+  See `:help gitsigns`.
+]]
+
 ---@type LazySpec
 return {
 { -- Adds git related signs to the gutter, as well as utilities for managing changes

lua/plugins/kickstart/plugins/guess_indent.lua

@@ -0,0 +1,19 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/guess_indent.lua
+  Module: plugins.kickstart.plugins.guess_indent
+
+  Purpose
+    Lazy spec for guess-indent.nvim: detects indentation style per buffer so new
+    lines match tabs vs. spaces without manual `:set sw=`.
+
+  Rationale
+    Lightweight, runs early in the spec list; no keymaps. Keeps indent behavior
+    consistent before Treesitter or LSP attach.
+
+  See plugin README; `:help 'shiftwidth'`.
+]]
+
+---@type LazySpec
+return {
+  { 'NMAC427/guess-indent.nvim', opts = {} },
+}

lua/plugins/kickstart/plugins/indent_line.lua

@@ -0,0 +1,26 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/indent_line.lua
+  Module: plugins.kickstart.plugins.indent_line
+
+  Purpose
+    Lazy spec for indent-blankline.nvim (`ibl`): optional vertical guides aligned
+    with indentation levels for readability in deeply nested code.
+
+  Rationale
+    Purely visual; lazy-loads via `main = 'ibl'`. Defaults are minimal; extend
+    `opts` if you want scope rules or excluded filetypes.
+
+  See `:help ibl.txt`.
+]]
+
+---@module 'lazy'
+---@type LazySpec
+return {
+  'lukas-reineke/indent-blankline.nvim',
+  -- Enable `lukas-reineke/indent-blankline.nvim`
+  -- See `:help ibl`
+  main = 'ibl',
+  ---@module 'ibl'
+  ---@type ibl.config
+  opts = {},
+}

lua/plugins/kickstart/plugins/lint.lua

@@ -1,4 +1,17 @@
--- Linting
+--[[
+  Path: lua/plugins/kickstart/plugins/lint.lua
+  Module: plugins.kickstart.plugins.lint
+
+  Purpose
+    Lazy spec for nvim-lint: asynchronous linters per filetype (here Markdown
+    via markdownlint) triggered on buffer enter / write / leaving Insert mode.
+
+  Rationale
+    Complements LSP diagnostics where you want CLI linters or faster feedback.
+    Extend `linters_by_ft` as you add tools to Mason or the host system.
+
+  See `:help nvim-lint.txt`.
+]]
 
 ---@module 'lazy'
 ---@type LazySpec

lua/plugins/kickstart/plugins/lsp.lua

@@ -1,3 +1,19 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/lsp.lua
+  Module: plugins.kickstart.plugins.lsp
+
+  Purpose
+    Lazy spec for nvim-lspconfig + Mason + blink.cmp integration: LspAttach
+    keymaps, server table (clangd, gopls, pyright, rust, ts_ls, lua_ls, etc.),
+    Mason tool installer, and 0.11 `vim.lsp.config` / `vim.lsp.enable` wiring.
+
+  Rationale
+    Concentrates all LSP lifecycle logic in one place. Blink is both a
+    dependency (capabilities) and a top-level plugin spec in `blink.lua`.
+
+  See `:help lsp`, `:help mason.nvim`, `:help blink.cmp`.
+]]
+
 ---@type LazySpec
 return {
 {

lua/plugins/kickstart/plugins/mini.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/mini.lua
+  Module: plugins.kickstart.plugins.mini
+
+  Purpose
+    Lazy spec for nvim-mini/mini.nvim: loads `mini.ai`, `mini.surround`, and
+    `mini.statusline` with nerd-font aware icons and a compact location section.
+
+  Rationale
+    Bundles small quality-of-life modules under one plugin id to reduce Lazy
+    node count; adjust `mini.ai` mappings if they collide with Treesitter.
+
+  See `:help mini.nvim`.
+]]
+
 ---@type LazySpec
 return {
 { -- Collection of various small independent plugins/modules

lua/plugins/kickstart/plugins/mini_icons.lua

@@ -0,0 +1,29 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/mini_icons.lua
+  Module: plugins.kickstart.plugins.mini_icons
+
+  Purpose
+    Lazy spec for mini.icons: consistent glyphs/highlights for special filenames
+    (e.g. `.go-version`) and filetypes like `gotmpl`.
+
+  Rationale
+    Complements web-devicons and Treesitter; keeps icon tweaks in one small
+    table instead of scattering `nvim_set_hl` calls.
+
+  See `:help mini.icons`.
+]]
+
+---@type LazySpec
+return {
+{
+  'nvim-mini/mini.icons',
+  opts = {
+    file = {
+      ['.go-version'] = { glyph = '', hl = 'MiniIconsBlue' },
+    },
+    filetype = {
+      gotmpl = { glyph = '󰟓', hl = 'MiniIconsGrey' },
+    },
+  },
+},
+}

lua/plugins/kickstart/plugins/neo-tree.lua

@@ -1,4 +1,17 @@
--- Neo-tree: https://github.com/nvim-neo-tree/neo-tree.nvim
+--[[
+  Path: lua/plugins/kickstart/plugins/neo-tree.lua
+  Module: plugins.kickstart.plugins.neo-tree
+
+  Purpose
+    Lazy spec for nvim-neo-tree/neo-tree.nvim: filesystem sidebar, reveal/toggle
+    keymaps, and tuned `filesystem` options (hidden files, libuv watcher, root).
+
+  Rationale
+    Centralizes file-tree UX; `<leader>x` / `<leader>z` maps live in keymaps.lua.
+    Kept separate from `custom.plugins` so “core” navigation stays discoverable.
+
+  See https://github.com/nvim-neo-tree/neo-tree.nvim
+]]
 
 ---@module 'lazy'
 ---@type LazySpec

lua/plugins/kickstart/plugins/neotest_golang.lua

@@ -0,0 +1,21 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/neotest_golang.lua
+  Module: plugins.kickstart.plugins.neotest_golang
+
+  Purpose
+    Lazy spec for neotest-golang: Neotest adapter for Go tests (table-driven,
+    subtests) when you wire Neotest core elsewhere.
+
+  Rationale
+    Declared as a standalone plugin entry so enabling `nvim-neotest/neotest`
+    later only requires adding the core plugin + runners; this stays inert until then.
+
+  See https://github.com/nvim-neotest/neotest and adapter README.
+]]
+
+---@type LazySpec
+return {
+{
+  'fredrikaverpil/neotest-golang',
+},
+}

lua/plugins/kickstart/plugins/render_markdown.lua

@@ -0,0 +1,27 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/render_markdown.lua
+  Module: plugins.kickstart.plugins.render_markdown
+
+  Purpose
+    Lazy spec for render-markdown.nvim: in-buffer Markdown preview (no external
+    server), with LaTeX disabled and LSP/blink completion hooks enabled.
+
+  Rationale
+    Filetype-limited load keeps startup lean; pairs with Treesitter + mini.nvim
+    as declared dependencies.
+
+  See plugin README; `:help render-markdown.nvim` if bundled.
+]]
+
+---@type LazySpec
+return {
+{
+  'MeanderingProgrammer/render-markdown.nvim',
+  dependencies = { 'nvim-treesitter/nvim-treesitter', 'nvim-mini/mini.nvim' },
+  ft = { 'markdown', 'markdown.mdx' },
+  opts = {
+    latex = { enabled = false },
+    completions = { lsp = { enabled = true }, blink = { enabled = true } },
+  },
+},
+}

lua/plugins/kickstart/plugins/spec.lua

@@ -0,0 +1,59 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/spec.lua
+  Module: plugins.kickstart.plugins.spec
+
+  Purpose
+    Builds the complete lazy.nvim plugin list: requires each per-plugin module,
+    normalizes return shapes (single spec vs. `{ spec }`), and returns one flat
+    `LazySpec` array for `lazy.setup()`.
+
+  Rationale
+    Splitting each plugin into its own file keeps diffs small and matches how
+    lazy.nvim expects multiple tables to be merged at setup time.
+
+  See `:help lazy.nvim-plugin-spec`, `:help LazySpec`.
+]]
+
+---@param out table
+---@param chunk LazySpec|LazySpec[]
+local function append_specs(out, chunk)
+  if type(chunk[1]) == 'string' then
+    out[#out + 1] = chunk
+    return
+  end
+  for i = 1, #chunk do
+    out[#out + 1] = chunk[i]
+  end
+end
+
+---@type LazySpec
+local specs = {}
+local mods = {
+  'plugins.kickstart.plugins.guess_indent',
+  'plugins.kickstart.plugins.gitsigns',
+  'plugins.kickstart.plugins.which_key',
+  'plugins.kickstart.plugins.render_markdown',
+  'plugins.kickstart.plugins.telescope',
+  'plugins.kickstart.plugins.lsp',
+  'plugins.kickstart.plugins.conform',
+  'plugins.kickstart.plugins.blink',
+  'plugins.kickstart.plugins.tokyonight',
+  'plugins.kickstart.plugins.todo_comments',
+  'plugins.kickstart.plugins.mini',
+  'plugins.kickstart.plugins.treesitter',
+  'plugins.kickstart.plugins.vim_helm',
+  'plugins.kickstart.plugins.neotest_golang',
+  'plugins.kickstart.plugins.mini_icons',
+  'plugins.kickstart.plugins.debug',
+  'plugins.kickstart.plugins.indent_line',
+  'plugins.kickstart.plugins.lint',
+  'plugins.kickstart.plugins.autopairs',
+  'plugins.kickstart.plugins.neo-tree',
+  'custom.plugins',
+}
+
+for _, mod in ipairs(mods) do
+  append_specs(specs, require(mod))
+end
+
+return specs

lua/plugins/kickstart/plugins/telescope.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/telescope.lua
+  Module: plugins.kickstart.plugins.telescope
+
+  Purpose
+    Lazy spec for telescope.nvim: fuzzy finder for files, grep, diagnostics,
+    git, help, and LSP pickers; includes fzf-native and ui-select extensions.
+
+  Rationale
+    Large `config` function registers `<leader>s*` maps and theme extensions.
+    Deferred `require('telescope.builtin')` from LSP attach remains valid.
+
+  See `:help telescope`, `:help telescope.setup()`.
+]]
+
 ---@type LazySpec
 return {
 { -- Fuzzy Finder (files, lsp, etc)

lua/plugins/kickstart/plugins/todo_comments.lua

@@ -0,0 +1,27 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/todo_comments.lua
+  Module: plugins.kickstart.plugins.todo_comments
+
+  Purpose
+    Lazy spec for todo-comments.nvim: highlights TODO/FIXME/HACK-style comment
+    tokens and can integrate with Telescope (optional).
+
+  Rationale
+    Purely visual aid for scanning large codebases; `signs = false` avoids
+    gutter clutter if you prefer highlight-only.
+
+  See https://github.com/folke/todo-comments.nvim
+]]
+
+---@type LazySpec
+return {
+{
+  'folke/todo-comments.nvim',
+  event = 'VimEnter',
+  dependencies = { 'nvim-lua/plenary.nvim' },
+  ---@module 'todo-comments'
+  ---@type TodoOptions
+  ---@diagnostic disable-next-line: missing-fields
+  opts = { signs = false },
+},
+}

lua/plugins/kickstart/plugins/tokyonight.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/tokyonight.lua
+  Module: plugins.kickstart.plugins.tokyonight
+
+  Purpose
+    Lazy spec for tokyonight.nvim: colorscheme plugin with high priority so it
+    loads before most UI; disables italic comments then sets `colorscheme`.
+
+  Rationale
+    Centralizes theme choice. Swap plugin name + `vim.cmd.colorscheme` here if
+    you change distributions.
+
+  See `:help colorscheme`, plugin README.
+]]
+
 ---@type LazySpec
 return {
 { -- You can easily change to a different colorscheme.

lua/plugins/kickstart/plugins/treesitter.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/treesitter.lua
+  Module: plugins.kickstart.plugins.treesitter
+
+  Purpose
+    Lazy spec for nvim-treesitter: parser install list, `TSUpdate` build step,
+    highlight/indent toggles, and `lazy = false` so buffers get treesitter early.
+
+  Rationale
+    Syntax/folds/indent for supported languages; `auto_install` pulls missing
+    parsers on demand. Ruby keeps vim regex highlighting per upstream note.
+
+  See `:help nvim-treesitter`.
+]]
+
 ---@type LazySpec
 return {
 { -- Highlight, edit, and navigate code

lua/plugins/kickstart/plugins/vim_helm.lua

@@ -0,0 +1,25 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/vim_helm.lua
+  Module: plugins.kickstart.plugins.vim_helm
+
+  Purpose
+    Lazy spec for towolf/vim-helm: sets `filetype=helm` on Helm templates so
+    Treesitter/YAML tooling attach to the correct grammar instead of plain YAML.
+
+  Rationale
+    Small filetype shim; loaded on `BufReadPre` before heavy YAML LSP hooks run.
+
+  See Helm tooling docs; plugin README.
+]]
+
+---@type LazySpec
+return {
+{
+  'towolf/vim-helm',
+  event = 'BufReadPre',
+  config = function()
+    -- This plugin automatically detects helm files (including .tpl)
+    -- and sets the filetype to "helm" instead of "yaml"
+  end,
+},
+}

lua/plugins/kickstart/plugins/which_key.lua

@@ -1,3 +1,18 @@
+--[[
+  Path: lua/plugins/kickstart/plugins/which_key.lua
+  Module: plugins.kickstart.plugins.which_key
+
+  Purpose
+    Lazy spec for which-key.nvim: discoverable pop-up of pending key sequences
+    and group labels for `<leader>` chains (search, toggle, git hunks, LSP).
+
+  Rationale
+    Loaded on `VimEnter` so it does not delay first screen paint. `spec` entries
+    document chains used elsewhere (Telescope, gitsigns, LSP maps).
+
+  See `:help which-key.nvim.txt`.
+]]
+
 ---@type LazySpec
 return {
 { -- Useful plugin to show you pending keybinds.