Agent Guidelines for Dotfiles Repository

Repository Overview

Personal configuration files (dotfiles) for Linux/macOS development environment including nvim, i3, tmux, zsh, and other tools. Managed with GNU Stow for symlink management.

Build/Deploy Commands

• make dump-keybindings - Export Cinnamon keybindings to file
• make load-keybindings - Import keybindings from file
• ansible-playbook ansible-home/.ansible/deploy-open-webui.yml -i ansible-home/.ansible/hosts.ini - Deploy with Ansible
• stow tool-name - Create symlinks for a specific tool configuration
• stow -D tool-name - Remove symlinks for a specific tool configuration
• tmux source-file ~/.tmux.conf - Reload tmux configuration
• nvim --headless "+Lazy! sync" +qa - Update Neovim plugins without UI

Testing

No test suite - This is a configuration repository. Testing is done by manual verification, starting new sessions, opening nvim to check LSP/plugin functionality, and sourcing shell configs.

Code Style Guidelines

Lua (Neovim, Awesome WM, Yazi configs)

Indentation: Use tabs for indentation File Structure:

• nvim plugins: Each plugin in nvim/.config/nvim/lua/plugins/plugin-name.lua
• Use return {} pattern for plugin specifications

return {
    {"author/plugin", config = function() ... end},
}

Keybinding Pattern:

vim.keymap.set("n", "<leader>ff", builtin.find_files, { desc = "Telescope find files" })
vim.g.mapleader = " "  -- Set before loading plugins

Error Handling: Use pcall() for safe module loading (see awesome/rc.lua). Wrap git/system calls in error checks:

if vim.v.shell_error ~= 0 then
    vim.api.nvim_echo({{ "Failed to clone lazy.nvim:\n", "ErrorMsg" }}, true, {})
    os.exit(1)
end

LSP Configuration:

local capabilities = require("cmp_nvim_lsp").default_capabilities()
lspconfig.gopls.setup({
    capabilities = capabilities,
    filetypes = {"go", "gomod", "gowork", "gotmpl"},
    settings = { completeUnimported = true, usePlaceholders = true },
})

Shell Scripts (Bash/Zsh)

Shebang: Use #!/usr/bin/env bash or #!/usr/bin/env sh Quoting: Always quote variables to prevent word splitting Exit on errors: Use set -euo pipefail where appropriate

Tmux Config:

• Use set -g for global options, set-window-option or setw for window options
• Use bind-key with descriptive comments
• Conditional locale setting for WSL:

if-shell "locale -a | grep -q 'C.utf8'" "set-environment -g LANG C.utf8"

Error Checking:

if ! command -v docker &> /dev/null; then
    echo "Docker not found"
    exit 1
fi

Python (Ranger commands)

Imports: Use standard import style with from __future__ import for Python 2/3 compatibility Class Structure: Use docstrings for command documentation, implement execute() and tab() methods

class my_edit(Command):
    """Documentation string visible in :c help"""
    def execute(self):
        if self.arg(1):
            target_filename = self.rest(1)

YAML (Ansible playbooks)

Indentation: 2 spaces (strict) Best Practices: Use descriptive task names, when: for conditionals, register: to capture command output, changed_when: to control when tasks report changes

File Organization

• Each tool has its own directory matching stow structure
• Config files go in tool-name/.config/tool-name/
• Root dotfiles (.zshrc, .tmux.conf) go in tool-name/ directory
• Use GNU Stow for symlink management
• Example: nvim/.config/nvim/, tmux/.tmux.conf, zsh/.zshrc

Naming Conventions

• Lua: snake_case for variables/functions, PascalCase for classes
• Shell: lowercase_with_underscores for functions and variables
• Python: snake_case for variables/functions, PascalCase for classes
• tmux: lowercase_with_underscores for options (@powerkit_option_name)
• File names: lowercase with hyphens or underscores

Security Guidelines

Pre-Commit Sensitive Data Check

CRITICAL: Always scan for sensitive data before committing. Run these checks:

rg -i "password|passwd|api_key|apikey|secret|token|private_key|credentials|bearer" --glob '!.git/*'
rg -i "aws_access_key|aws_secret|github_token|gh_token|ssh_key" --glob '!.git/*'
find . -name "*.pem" -o -name "*.key" -o -name "*.env" -o -name "*_rsa" 2>/dev/null | grep -v ".git"
git ls-files | rg -i "ssh|gpg|key|secret|password|credential"

What Should NEVER Be Committed

• SSH keys (id_rsa, id_ed25519, *.pem)
• GPG private keys
• API keys, tokens, or authentication credentials
• .env files with secrets (already in .gitignore)
• Email addresses or usernames (use placeholders in examples)
• IP addresses or hostnames (use localhost or example.com)

Safe to Commit

• Keyboard shortcuts and keybindings
• Theme configurations and color schemes
• Public configuration without credentials
• Example configs with placeholder values

Platform-Specific Considerations

• WSL: May need C.utf8 locale instead of en_US.UTF-8
• macOS: Separate zsh config in zsh-macos/ directory
• Linux: Use Linux-specific paths and tools

.gitignore

Excluded files: .aider*, .env, lazy-lock.json, .venv

Repository Structure

This repository is organized as a GNU Stow collection with each tool having its own directory:

• zsh/ - Zsh shell configuration with Oh My Zsh
• zsh-macos/ - macOS-specific Zsh configuration
• tmux/ - Tmux terminal multiplexer configuration
• alacritty/ - Alacritty terminal configuration
• kitty/ - Kitty terminal configuration
• kitty-mac/ - macOS-specific Kitty configuration
• i3/ - i3 window manager configuration
• awesome/ - Awesome window manager configuration
• polybar/ - Status bar configuration
• rofi/ - Application launcher configuration
• dunst/ - Notification daemon configuration
• ranger/ - Terminal file manager configuration
• yazi/ - Modern terminal file manager configuration
• newsraft/ - RSS reader configuration
• ansible-home/ - Ansible deployment automation
• autorandr-home-desktop/ - Monitor profile management
• ulauncher/ - Application launcher with extensions

Working with This Repository

1. All configuration files are designed to be portable across Linux/macOS systems
2. Use GNU Stow to deploy configurations: stow tmux, stow zsh
3. For macOS systems, use zsh-macos and kitty-mac instead of zsh and kitty
4. For WSL, ensure proper Nerd Font setup in Windows Terminal
5. Keybinding management uses make dump-keybindings and make load-keybindings for Cinnamon desktop

Key Features and Tools

• Zsh: Oh My Zsh with starship prompt
• Tmux: Includes tmux-powerkit plugin with powerline status bar
• Alacritty: GPU-accelerated terminal with Catppuccin themes
• Kitty: Alternative terminal with Catppuccin themes
• i3: Tiling window manager with configured keybindings
• Awesome: Lua-based window manager
• Themes: Consistent Catppuccin theming across most terminal tools
• Tools: Ranger, Yazi, Rofi, Dunst, Ulauncher, Newsraft

Configuration Management

• History settings in zsh are configured to prevent truncation and duplicate entries
• Tmux plugins require manual installation with Ctrl+a I after reloading configuration
• All configurations are designed for reuse across different machines

Target Audience

This repository is intended for experienced users who understand the tools and configuration concepts. README files are kept concise and focused on platform-specific differences rather than detailed explanations of basic functionality.