# Neovim Setup

## Initial setup flow

1. List/update plugins in `lua/setup/packages.lua`.
2. List/update language specs in `lua/modules/language-specs.lua`.
3. Run `nvim --headless +Setup +qa`.
4. Run `nvim --headless +FetchLspConfigs +qa`.

If `prettierd` is stuck, run `pkill prettierd` and re-run install commands.

## Where to put what

- `lua/setup/packages.lua`: plugin package list managed by Paq.
- `lua/modules/language-specs.lua`: language spec source of truth.
- `lsp/*.lua`: native Neovim LSP config files (fetched by `FetchLspConfigs`).

## Setup commands

- `:Setup`
  - bootstraps Paq if needed
  - installs plugins
  - installs treesitter parsers + Mason tools (LSP/linters/formatters)

- `:InstallPackages` (included in `:Setup`)
  - bootstraps Paq if needed
  - installs plugins

- `:InstallLanguages` (included in `:Setup`)
  - installs language tooling from language specs (treesitter + Mason tools)

- `:FetchLspConfigs` (manually executed after modifying language-specs)
  - fetches default `nvim-lspconfig` server config files
  - writes them into `~/.config/nvim/lsp`
  - skips files that already exist

- `:Sync`
  - runs Paq sync for plugin updates/cleanup

## Language specs: how they work

Each item in `lua/modules/language-specs.lua` can define:

- `ft`: one filetype or a list of filetypes
- `ts`: treesitter parser(s)
- `lsp`: Mason package name(s) for language servers
- `lint`: Mason package name(s) for linters
- `format`: Mason package name(s) for formatters

One spec file drives all three layers together:

1. install layer
   - treesitter parsers are installed via `nvim-treesitter`
   - LSP/lint/format tools are installed via Mason
2. runtime layer
   - native Neovim `vim.lsp.enable(...)` starts the resolved LSP configs
   - `nvim-lint` is configured by filetype
   - `conform.nvim` is configured by filetype
3. config layer
   - `FetchLspConfigs` downloads matching `lsp/*.lua` server configs for Neovim 0.11+

Important: for `lsp`, use Mason package names from:
`https://github.com/mason-org/mason-registry/tree/main/packages`

## Add a new language

1. Add/update a spec in `lua/modules/language-specs.lua`.
2. Run `nvim --headless +InstallLanguages +qa`.
3. Run `nvim --headless +FetchLspConfigs +qa`.
4. Open Neovim and run `:checkhealth vim.lsp` if needed.