A personal Neovim configuration running on **Neovim 0.12+**, managed by [lazy.nvim](https://github.com/folke/lazy.nvim).

---

## Directory Structure

```
Charvim/
├── nvim/
│   ├── after/
│   │   └── ftplugin/
│   │       ├── cobol.lua           # COBOL-specific settings
│   │       └── make.lua            # Makefile-specific settings
│   ├── colors/
│   │   └── noir-cat.lua            # Custom noir-cat colorscheme
│   ├── lua/
│   │   ├── img/
│   │   │   └── charVim.txt         # ASCII art for the dashboard
│   │   ├── alpha-config.lua        # Dashboard configuration
│   │   ├── autoclose.lua           # Auto-closing brackets and quotes
│   │   ├── completion-config.lua   # nvim-cmp completion config
│   │   ├── dap-config.lua          # Debugger configuration
│   │   ├── harpoon-config.lua      # Harpoon keymaps and setup
│   │   ├── keymaps.lua             # Custom keybindings
│   │   ├── lint-config.lua         # Linter configuration (nvim-lint)
│   │   ├── lsp-config.lua          # LSP settings and handlers
│   │   ├── multicursor.lua         # Custom multi-cursor implementation
│   │   ├── options.lua             # General Neovim options
│   │   ├── plugins.lua             # Plugin definitions via lazy.nvim
│   │   ├── rename-config.lua       # Find & replace / rename UI
│   │   ├── statusline.lua          # Custom mode-aware statusline
│   │   ├── theme-switcher.lua      # Runtime theme cycling
│   │   └── treesitter-config.lua   # Treesitter setup
│   └── init.lua                    # Main entry point
```

---

## Leader Keys

| Key | Value |
|-----|-------|
| `<leader>` | `Space` |
| `<localleader>` | `\` |

Leader key timeout: **500ms**

---

## Keybindings

> [!TIP]
> This section covers **custom** keybindings. For **standard Neovim motions** (like `h/j/k/l`, `w`, `b`, etc.), please refer to the [HOME.md](./Home.md) file.

### General

| Keys | Mode | Action |
|------|------|--------|
| `jk` | Insert | Escape to normal mode |
| `<leader>w` | Normal | Save file (`:w`) |
| `<leader>q` | Normal | Save and quit (`:wq`) |
| `<leader>qq` | Normal | Quit without saving (`:q!`) |
| `;` | Normal | Shortcut to shell command (`:!`) |

### Navigation

| Keys | Mode | Action |
|------|------|--------|
| `[[` | Normal | Go to beginning of file (`gg`) |
| `]]` | Normal | Go to end of file (`G`) |
| `H` | Normal/Visual | **Custom:** Go to beginning of line (`0`) |
| `L` | Normal/Visual | **Custom:** Go to end of line (`$`) |
| `Alt+[` | Normal/Visual | Previous paragraph (`{`) |
| `Alt+]` | Normal/Visual | Next paragraph (`}`) |
| `Ctrl+h/j/k/l` | Normal | Navigate splits (also integrates with tmux panes) |

### Line Manipulation

| Keys | Mode | Action |
|------|------|--------|
| `Alt+k` / `Alt+j` | Normal | Move line up / down |
| `Alt+k` / `Alt+j` | Visual | Move selection up / down |
| `Ctrl+k` / `Ctrl+j` | Insert | Move line up / down |
| `Ctrl+Shift+k` / `Ctrl+Shift+j` | Normal | Copy (duplicate) line up / down |
| `Ctrl+Shift+k` / `Ctrl+Shift+j` | Visual | Copy selection up / down |

### File Explorer (Telescope File Browser)

| Keys | Mode | Action |
|------|------|--------|
| `<leader>e` | Normal | Open file browser at current file's directory |
| `<leader>E` | Normal | Open file browser at project root (`.git`, `package.json`, etc.) |
| `<leader>t` | Normal | Open new tab with file browser |
| `:E` or `:Tree` | Command | Open file browser |

### Telescope

| Keys | Context | Action |
|------|---------|--------|
| `<leader>g` | Normal | Live grep |
| `<leader>p` | Normal | Projects picker |
| `Ctrl+.` | Telescope insert mode | Toggle hidden files |
| Dashboard `f` | Alpha | Find file |
| Dashboard `p` | Alpha | Projects |
| Dashboard `g` | Alpha | Find text (live grep) |
| Dashboard `r` | Alpha | Recent files |

Hidden files are shown by default. `.git/` directories are always ignored.

### Harpoon 2

| Keys | Mode | Action |
|------|------|--------|
| `<leader>a` | Normal | Add current file to Harpoon list |
| `<leader>ar` | Normal | Remove current file from Harpoon list |
| `<leader>ac` | Normal | Clear all Harpoon marks |
| `<leader>h` | Normal | Toggle Harpoon quick menu |
| `Alt+1` through `Alt+5` | Normal | Jump to Harpoon file 1–5 |
| `Alt+n` / `Alt+p` | Normal | Next / previous Harpoon file |

### Multi-Cursor

| Keys | Mode | Action |
|------|------|--------|
| `Ctrl+n` | Normal | Enter multi-cursor mode |
| `Ctrl+Up` | Normal/Visual | Add cursor above |
| `Ctrl+Down` | Normal/Visual | Add cursor below |
| `j` / `k` | Normal (multi-cursor active) | Move down/up and extend cursors |
| `Esc` | Normal (multi-cursor active) | Exit multi-cursor mode |

In multi-cursor mode, entering insert mode types at all cursor positions simultaneously.

### Find & Replace / Rename

| Keys | Mode | Action |
|------|------|--------|
| `<leader>S` | Normal | Open find & replace / rename panel |
| `<leader>S` | Visual | Open panel pre-filled with selected text |
| `:Find` | Command | Same as `<leader>S` |

The panel has three sections: **Find**, **Replace**, and a **Results list** with a live preview pane.

| Keys | Context | Action |
|------|---------|--------|
| `Tab` | Any panel | Cycle focus between Find → Replace → Results |
| `j` / `k` or `Up` / `Down` | Results list | Navigate matches |
| `y` | Results list | Accept replacement for the highlighted match |
| `Y` | Any panel | Accept replacement for **all** matches |
| `Enter` | Replace panel or Results | Accept all (same as `Y`) |
| `Enter` | Results list | Jump to match in file |
| `Esc` / `q` | Any panel | Close |

When the find term matches an identifier under an active LSP client with rename support, `Y` uses **LSP rename** instead of regex substitution.

### Runners

| Keys | Mode | Action |
|------|------|--------|
| `<leader>ob` | Normal | Open HTML file in browser |
| `<leader>rp` | Normal | Run current Python file in split terminal |
| `<leader>rj` | Normal | Compile and run current Java file in split terminal |

### LSP

| Keys | Mode | Action |
|------|------|--------|
| `K` | Normal | Hover documentation |
| `gd` | Normal | Go to definition |
| `gD` | Normal | Go to declaration |
| `gi` | Normal | Go to implementation |
| `go` | Normal | Go to type definition |
| `gr` | Normal | Show references |
| `gs` | Normal | Signature help |
| `<leader>lr` | Normal | Rename symbol (LSP) |
| `<leader>ca` | Normal | Code action |
| `<leader>le` | Normal | Open diagnostic float |
| `[d` / `]d` | Normal | Previous / next diagnostic |
| `<leader>ih` | Normal | Toggle inlay hints |
| `<leader>ig` | Normal | Add word under cursor to dictionary (ltex/typos_lsp) |
| `<leader>di` | Normal | Inspect diagnostics at cursor |

### Java (buffer-local, active in `.java` files)

| Keys | Mode | Action |
|------|------|--------|
| `<leader>jb` | Normal | Build project (Maven/Gradle/Ant auto-detected) |
| `<leader>jt` | Normal | Run tests |
| `<leader>jc` | Normal | Clean project |
| `<leader>jw` | Normal | Clean JDTLS workspace cache |

### Kotlin (buffer-local, active in `.kt` files)

| Keys | Mode | Action |
|------|------|--------|
| `<leader>kb` | Normal | Build project (Gradle/Maven auto-detected) |
| `<leader>kt` | Normal | Run tests |
| `<leader>kc` | Normal | Clean project |
| `<leader>kr` | Normal | Run project |

### Completion (nvim-cmp)

| Keys | Mode | Action |
|------|------|--------|
| `Tab` / `Shift+Tab` | Insert | Cycle through completion items |
| `Enter` | Insert | Confirm selected completion |

### Debugging (DAP)

| Keys | Mode | Action |
|------|------|--------|
| `<leader>db` | Normal | Toggle breakpoint |
| `<leader>dB` | Normal | Set conditional breakpoint |
| `<leader>dc` | Normal | Continue |
| `<leader>dn` | Normal | Step over |
| `<leader>di` | Normal | Step into |
| `<leader>do` | Normal | Step out |
| `<leader>dr` | Normal | Open REPL |
| `<leader>dl` | Normal | Run last configuration |
| `<leader>dt` | Normal | Terminate session |
| `<leader>du` | Normal | Toggle DAP UI |
| `<leader>dp` | Normal | Debug Python method under cursor |

The DAP UI opens automatically when a session starts and closes when it ends.

### AI (avante.nvim)

| Keys | Mode | Action |
|------|------|--------|
| `Alt+Enter` | Insert | Accept inline suggestion |
| `Alt+]` | Insert | Next suggestion |
| `Ctrl+]` | Insert | Dismiss suggestion |

### Linting

| Keys | Mode | Action |
|------|------|--------|
| _Auto_ | BufWritePost/BufEnter | Lint file on save and entry |

### Themes

| Keys | Mode | Action |
|------|------|--------|
| Dashboard `t` | Alpha | Open theme picker |
| `:ThemeSelect` | Command | Open interactive theme picker |
| `:Theme <name>` | Command | Switch to a specific theme by name |

### Tree-sitter Incremental Selection

| Keys | Mode | Action |
|------|------|--------|
| `gnn` | Normal | Init selection |
| `grn` | Normal | Expand to next node |
| `grc` | Normal | Expand to scope |
| `grm` | Normal | Shrink selection |

### Dashboard

| Keys | Mode | Action |
|------|------|--------|
| `<leader>d` | Normal | Open Alpha dashboard |

---

## Plugins

### Plugin Manager
- **lazy.nvim** — Lazy-loading plugin manager. Clone depth set to 1 with 120s timeout for reliable installs.

### Themes
- **rose-pine** (`Knew-pines` variant) — Transparent background, gold cursor line number.
- **tokyonight** (night style) — Transparent.
- **catppuccin** (mocha flavour) — Transparent.
- **gruvbox** — Transparent mode.
- **noir-cat** — Custom dark colorscheme defined in `nvim/colors/noir-cat.lua`.
- **habamax** — Built-in Neovim colorscheme.
- **theme-switcher** (custom module) — Cycle between all themes at runtime via `:ThemeSelect` or `:Theme <name>`. Selection persists across restarts.

Available theme names: `Auto`, `Knew-pines`, `Noir-cat`, `Tokyo Night`, `Catppuccin`, `Gruvbox`, `Habamax`.

### UI
- **noice.nvim** — Replaces the command line with a centered popup. Messages and popupmenu backends disabled in favour of nvim-cmp.
- **alpha-nvim** — Dashboard/start screen with ASCII art logo and quick-access buttons (find file, projects, new file, recent files, live grep, config, lazy, mason, themes, quit).
- **which-key.nvim** — Displays available keybindings in a popup (modern preset).

### Navigation & File Management
- **telescope.nvim** + **telescope-file-browser.nvim** — Fuzzy finder and file browser. Replaces netrw. Shows hidden files by default.
- **project.nvim** — Project detection and management via Telescope. Detects by LSP root or pattern (`.git`, `Makefile`, `package.json`, `pom.xml`, `build.gradle`, `Cargo.toml`).
- **harpoon** (v2) — Quick file bookmarking and navigation. Saves on toggle, syncs on UI close.
- **vim-tmux-navigator** — Seamless navigation between Neovim splits and tmux panes with `Ctrl+h/j/k/l`.

### Editing
- **nvim-surround** — Add, change, and delete surrounding pairs (quotes, brackets, tags, etc.).
- **multicursor** (custom module) — Native multi-cursor implementation. Broadcasts insert-mode changes and dot-repeat to all cursor positions. No external dependencies.
- **autoclose** (custom module) — Auto-closes brackets, quotes, and backticks. Handles escape-through-closing-char, backspace-deletes-pair, and enter-opens-block. Also works in command mode and visual mode (wrap selection).
- **rename-config** (custom module) — Find & replace / rename panel backed by `rg`. Uses LSP rename when the find term is an unchanged identifier with a rename-capable LSP client, otherwise falls back to regex substitution via quickfix (`cfdo`).

### LSP & Diagnostics
- **mason.nvim** — LSP server, linter, and DAP installer.
- LSP servers are registered directly with `vim.lsp.config()` / `vim.lsp.enable()` (no mason-lspconfig).
- Inlay hints enabled by default where supported (toggle with `<leader>ih`).
- Diagnostic noise from ltex (sentence/paragraph length, "This sentence…") is filtered out globally.

#### Configured LSP Servers

| Server | Languages | Notes |
|--------|-----------|-------|
| `lua_ls` | Lua | Auto-installed via Mason |
| `pyright` | Python | Auto-installed via Mason |
| `ts_ls` | TypeScript / JavaScript / Vue | Auto-installed via Mason |
| `jdtls` | Java | Per-project workspace dirs, Maven/Gradle/Ant auto-detect, code lens enabled, GoogleStyle format |
| `kotlin_language_server` | Kotlin | JVM target 17, type and parameter inlay hints |
| `gopls` | Go | Unused param + shadow analysis, gofumpt, full inlay hints |
| `clangd` | C / C++ / Obj-C / Obj-C++ | Auto-installed via Mason |
| `tinymist` | Typst | Exports PDF on save |
| `sourcekit-lsp` | Swift / Obj-C / Obj-C++ | System binary; lazy-enabled on filetype |
| `lemminx` | XML | Auto-installed via Mason |

### Completion
- **nvim-cmp** — Completion engine with sources:
  - `nvim_lsp` — LSP completions
  - `buffer` — Buffer word completions
- **LuaSnip** — Snippet engine (used for LSP snippet expansion).

### AI
- **avante.nvim** — AI-assisted code chat and editing using Anthropic Claude (`claude-haiku-4-5`). Auto-suggestions disabled; invoke manually via the avante UI. Requires `ANTHROPIC_API_KEY` set in the `.env` file next to `nvim/`.

### Linting
- **nvim-lint** — Configurable linting via `lint-config.lua`. Auto-lints on `BufWritePost` and `BufEnter`.

| Language | Linter |
|----------|--------|
| Lua | `luacheck` |
| Go | `staticcheck` |
| Python | `ruff` |
| JavaScript / TypeScript | `eslint_d` |
| Java | `checkstyle` |
| Kotlin | `ktlint` |

### Debugging (DAP)
- **nvim-dap** + **nvim-dap-ui** — Debug Adapter Protocol. UI opens automatically on session start and closes on exit.
- **mason-nvim-dap** — Ensures DAP adapters are installed: `python`, `javadbg`, `codelldb`, `kotlin`.

| Language | Adapter | Notes |
|----------|---------|-------|
| Python | `dap-python` | `pytest` as test runner |
| Java | `jdtls` built-in | Attach to process or launch by main class |
| C / C++ | `codelldb` | Prompts for executable path |
| Swift | `codelldb` | Defaults to `.build/debug/` |
| Kotlin | `kotlin-debug-adapter` | Launch by main class or attach on port 5005 |

### Syntax & Parsing
- **nvim-treesitter** — Syntax highlighting, indentation, and incremental selection. Auto-installs missing parsers. Disables highlighting for files > 100KB.
- Installed parsers: c, lua, vim, vimdoc, query, javascript, typescript, python, rust, go, html, css, json, markdown, bash, yaml, toml, xml, kotlin.
- Crystal files (`.cr`) fall back to Ruby syntax highlighting.
- `.plist` files are treated as XML.
- **nvim-ts-autotag** — Auto-closes and auto-renames HTML/JSX tags.

### Document Authoring
- **typst-preview.nvim** — Live browser preview for Typst files. Custom commands: `:TP` (start), `:TS` (stop), `:TU` (update).

---

## Editor Options

| Option | Value |
|--------|-------|
| Line numbers | On (absolute) |
| Relative numbers | On |
| Tab width | 4 spaces (expandtab) |
| Smart indent | On |
| Swap files | Off |
| Backup files | Off |
| Clipboard | System clipboard (`unnamedplus`) |
| Scroll offset | 10 lines |
| Encoding | UTF-8 |
| Cursor line | Highlighted (number only, gold color) |
| Cursor shape | Block in normal/visual, vertical bar in insert, horizontal bar in replace |
| Command line height | 0 (hidden) |
| Whitespace chars | Visible (tab `▸`, trail `·`, extends `»`, precedes `«`, nbsp `␣`, leading `│`) |
| Background | Transparent (both Normal and NormalFloat) |
| Undo | Persistent (stored in Neovim data dir) |
| Incremental substitute | Split preview (`inccommand = split`) |

---

## Statusline

Custom-built statusline (no plugin). Displays:
- **Left:** Mode indicator letter + filename + modified flag `[+]`
- **Right:** Save flash (`written`, shown for 2s after save) + current mode name + percentage + column

Mode names: NORMAL, INSERT, VISUAL, V-LINE, V-BLOCK, COMMAND, SELECT, S-LINE, S-BLOCK, REPLACE, SHELL, TERMINAL.

Mode indicator colours:

| Mode | Colour |
|------|--------|
| Normal | Gold `#f6c177` |
| Insert | Foam `#9ccfd8` |
| Visual | Iris `#c4a7e7` |
| Command | Love `#eb6f92` |
| Replace | Love `#eb6f92` |

---

## Filetype-Specific Settings

### COBOL (`after/ftplugin/cobol.lua`)
- Tab width: 8 spaces
- Color columns at 7 and 73 (traditional fixed-format margins)
- Text width: 72
- Absolute line numbers, no relative numbers

### Makefile (`after/ftplugin/make.lua`)
- Makefile-specific settings and options.

### Crystal
- `.cr` files mapped to `crystal` filetype
- Falls back to Ruby syntax highlighting

### Java
- Build system auto-detected (Maven `pom.xml`, Gradle `build.gradle`/`build.gradle.kts`, Ant `build.xml`)
- JDTLS workspace directories stored in `~/.cache/nvim/jdtls/<project_name>`
- Code lens enabled, GoogleStyle format profile
- Buffer-local build keymaps: `<leader>jb/jt/jc/jw`

### Kotlin
- Build system auto-detected (Gradle or Maven)
- Buffer-local build keymaps: `<leader>kb/kt/kc/kr`

---

## Custom Commands

| Command | Action |
|---------|--------|
| `:E` | Open Telescope file browser |
| `:Tree` | Open Telescope file browser |
| `:Find` | Open find & replace / rename panel |
| `:TP` | Start Typst preview |
| `:TS` | Stop Typst preview |
| `:TU` | Update Typst preview |
| `:ThemeSelect` | Open interactive theme picker |
| `:Theme <name>` | Switch to a specific theme |
| `:OpenInBrowser` | Open current HTML file in browser |
| `:RunPython` | Run current Python file |
| `:RunJava` | Run current Java file |

---

## Notes

- Plugin versions are locked in `nvim/lazy-lock.json`. Run `:Lazy update` to update and `:Lazy restore` to roll back.
- Mason-managed tools are stored in Neovim's data directory (`~/.local/share/nvim/mason/`).
- The autoclose, multicursor, and rename-config modules are custom implementations (not plugins).
- `ANTHROPIC_API_KEY` must be set in the `.env` file adjacent to `nvim/` for avante.nvim to work.
- Theme selection is persisted to Neovim's data directory and restored on next launch.