Vim Keymapping Conventions

This rule applies to files matching the patterns above.

# Vim Keymapping Conventions

## Rule
All custom keymappings MUST use the leader key prefix, include descriptions, and NEVER override built-in Vim motions.

## Format
```lua
-- Neovim Lua format (required)
vim.keymap.set("n", "<leader>ff", "<cmd>Telescope find_files<cr>", { desc = "Find files" })
vim.keymap.set("n", "<leader>fg", "<cmd>Telescope live_grep<cr>", { desc = "Live grep" })
```

## Requirements

### Leader Key
- Set to Space: `vim.g.mapleader = " "`
- All custom mappings use `<leader>` prefix
- Group by function: `<leader>f` = find, `<leader>g` = git, `<leader>l` = LSP

### Descriptions Required
```lua
-- Good: includes desc for which-key and help
vim.keymap.set("n", "<leader>e", "<cmd>NvimTreeToggle<cr>", { desc = "Toggle file explorer" })

-- Bad: no description
vim.keymap.set("n", "<leader>e", "<cmd>NvimTreeToggle<cr>")
```

### Never Override Core Motions
```lua
-- NEVER do these:
vim.keymap.set("n", "j", "gj")   -- Overrides core motion
vim.keymap.set("n", "s", ...)     -- Overrides substitute
vim.keymap.set("n", "H", ...)     -- Overrides high jump
vim.keymap.set("n", "L", ...)     -- Overrides low jump

-- Acceptable exceptions:
vim.keymap.set("n", "j", "v:count == 0 ? 'gj' : 'j'", { expr = true })  -- Smart j
```

### Keymap Organization
```lua
-- Group by namespace
-- <leader>f = Find/Files
-- <leader>g = Git
-- <leader>l = LSP
-- <leader>b = Buffers
-- <leader>w = Windows
-- <leader>t = Terminal/Toggle
```

## Good Examples
```lua
vim.keymap.set("n", "<leader>ff", "<cmd>Telescope find_files<cr>", { desc = "Find files" })
vim.keymap.set("n", "<leader>gs", "<cmd>Telescope git_status<cr>", { desc = "Git status" })
vim.keymap.set("n", "<leader>ld", vim.lsp.buf.definition, { desc = "Go to definition" })
vim.keymap.set("n", "<leader>lr", vim.lsp.buf.references, { desc = "Find references" })
```

## Bad Examples
```lua
vim.keymap.set("n", "ff", ...)         -- No leader prefix
vim.keymap.set("n", "<leader>a", ...)  -- Non-descriptive key
vim.keymap.set("n", "w", ...)          -- Overrides word motion!
```