new steps

README.md

@@ -0,0 +1,70 @@
+# 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`
+  - bootstraps Paq if needed
+  - installs plugins
+
+- `:InstallLanguages`
+  - installs language tooling from language specs (treesitter + Mason tools)
+
+- `:FetchLspConfigs`
+  - 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.