Dotfiles Configuration Management

Expert assistant for managing a modular dotfiles repository with multi-context support and synchronized Vim configurations across Neovim, IdeaVim, and Cursor.

Repository Structure

This dotfiles repository follows a modular architecture where each tool has its own directory:

Critical Principles

1. Vim Configuration Synchronization

**MOST IMPORTANT**: Neovim, IdeaVim, and Cursor configurations MUST be kept as similar as possible for workflow consistency.

When modifying any vim setup:

1. Analyze the change impact on other vim environments

2. Update all three configurations to maintain feature parity

3. Test keybindings across all environments

**Shared keybinding conventions:**

2. Manual Symlink Management

This repository uses **explicit symlinks only** (no install scripts).

**Symlink pattern:**

```bash

ln -sf ~/.dotfiles/<tool>/config-file ~/.config/<tool>/config-file

```

**Existing symlinks:**

```bash

ln -s ~/.dotfiles/ideavim/.ideavimrc ~/.ideavimrc

ln -s ~/.dotfiles/tmux/.tmux.conf ~/.tmux.conf

ln -s ~/.dotfiles/zsh/.zshrc ~/.zshrc

ln -s ~/.dotfiles/aerospace/.config/aerospace/aerospace.toml ~/.config/aerospace/aerospace.toml

ln -sf ~/.dotfiles/yazi ~/.config/yazi

ln -sf ~/.dotfiles/cursor/settings.json ~/Library/Application\ Support/Cursor/User/settings.json

ln -sf ~/.dotfiles/cursor/keybindings.json ~/Library/Application\ Support/Cursor/User/keybindings.json

```

3. Multi-Context Git Workflow

Support personal and work contexts via separate configuration directories:

Step-by-Step Instructions

When Adding a New Tool Configuration

1. Create a new directory: `~/.dotfiles/<tool-name>/`

2. Add configuration files inside the tool directory

3. Create symlink from `~/.config/<tool-name>/` or home directory to the dotfiles location

4. Document the symlink command in this guide

5. Test the configuration by reloading (see reload commands below)

6. Commit with conventional commit format: `feat(tool-name): add initial configuration`

When Modifying Vim Configurations

1. **Identify the scope**: Does this change affect keybindings, LSP, or UI?

2. **Check all three vim environments**: Neovim (`nvim/init.lua`), IdeaVim (`.ideavimrc`), Cursor (`settings.json` + `keybindings.json`)

3. **Apply equivalent changes** to maintain feature parity

4. **Test in all environments**:

- Neovim: Restart or `:source %`

- IdeaVim: Restart IntelliJ IDEA

- Cursor: Restart Cursor IDE

5. **Document if keybinding patterns change**

When Adding Neovim Plugins

1. Add plugin specification to `nvim/lua/custom/plugins/` or `nvim/lua/kickstart/plugins/`

2. Follow lazy.nvim conventions (lazy-loading, dependencies)

3. Configure LSP servers via Mason if needed (`:Mason`)

4. Add keybindings following the established prefixes

5. Check for conflicts with AeroSpace window manager keybindings

6. Update equivalent functionality in IdeaVim and Cursor if applicable

Reloading Configurations

```bash

tmux

tmux source-file ~/.tmux.conf # or C-b r inside tmux

AeroSpace

alt-shift-semicolon then r

Neovim

Restart nvim or :source % on current file

yazi

Restart yazi

zsh

source ~/.zshrc # or open new terminal

Cursor

Settings reload automatically; full restart recommended for keybindings

```

When Troubleshooting Configurations

1. Check if symlinks are correct: `ls -la ~/.config/<tool>/ | grep dotfiles`

2. Verify source files exist: `cat ~/.dotfiles/<tool>/config-file`

3. Check for syntax errors in configuration files

4. Review recent commits: `git log --oneline -10`

5. Test with minimal configuration if needed

6. Check tool-specific logs:

- Neovim: `:messages` and `:checkhealth`

- tmux: `tmux info`

- zsh: `echo $?` after sourcing

Neovim Architecture

**Required dependencies**: git, make, unzip, C compiler, ripgrep, clipboard tool, Nerd Font (optional)

Development Guidelines

1. **Consistency**: Follow existing patterns within each tool's configuration

2. **Vim-first**: Maintain vim-style navigation across all tools

3. **Conflict awareness**: Check AeroSpace keybindings when adding new shortcuts

4. **Language**: Configuration files may contain Polish comments from original author (preserve or translate as appropriate)

5. **Commit style**: Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`

6. **Modularity**: Keep tools independent - adding/removing one shouldn't affect others

Examples

Example 1: Adding a new keybinding to all vim environments

```lua

-- nvim/init.lua or plugin file

vim.keymap.set('n', '<leader>fb', '<cmd>Telescope buffers<cr>', { desc = '[F]ind [B]uffers' })

```

```vim

" .ideavimrc

nnoremap <leader>fb :action RecentFiles<CR>

```

```json

// cursor/keybindings.json

{

"key": "space f b",

"command": "workbench.action.showAllEditors",

"when": "vim.active && vim.mode == 'Normal'"

}

```

Example 2: Adding a new tool configuration

```bash

Create directory structure

mkdir -p ~/.dotfiles/alacritty

Add configuration file

cat > ~/.dotfiles/alacritty/alacritty.yml << 'EOF'

Alacritty configuration

window:

opacity: 0.95

EOF

Create symlink

ln -sf ~/.dotfiles/alacritty/alacritty.yml ~/.config/alacritty/alacritty.yml

Test

alacritty --version

Commit

git add alacritty/

git commit -m "feat(alacritty): add initial configuration"

```

Constraints