diff --git a/README.md b/README.md
index 8aba315..6a487fa 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,32 @@
 # Dotfiles
 
-Minimal dotfiles for Ubuntu servers. Optimized for development over SSH.
+Minimal symlink-based dotfiles for SSH development. XDG-compliant, distro-aware, <100ms startup.
+
+## What's Inside
+
+**Shell Environment:**
+- `.zshrc` - Zsh config with vi mode, starship prompt, fzf integration
+- `.zprofile` - Zsh profile (login shell setup)
+- `.aliases` - Shell aliases with distro detection (Debian/Arch)
+- `distro/` - Distro-specific aliases (apt/pacman)
+- `inputrc` - Readline configuration
+
+**Development Tools:**
+- `init.vim` - Neovim config (Gruvbox, git, FZF, linting)
+- `.tmux.conf` - Tmux config (backtick prefix, vim nav, persistence)
+- `.gitconfig` - Git config with delta pager, shortcuts (gs, ga, gc)
+- `.gitconfig.local.example` - Template for personal git info
+- `starship.toml` - Starship prompt configuration
+
+**Bookmark System:**
+- `bm-dirs` - Directory bookmarks (cf → ~/.config)
+- `bm-files` - File bookmarks (ez → ~/.zshrc)
+- `generate-shortcuts.sh` - Auto-generate shortcuts from bookmarks
+
+**Management:**
+- `install.sh` - Symlink installer with automatic backups
+- `rollback.sh` - Restore from backup
+- `tests/` - Docker-based automated testing
 
 ## Quick Install
 
@@ -8,162 +34,59 @@ Minimal dotfiles for Ubuntu servers. Optimized for development over SSH.
 git clone https://github.com/maxrantil/dotfiles.git ~/.dotfiles
 cd ~/.dotfiles
 ./install.sh
-```
-
-## Rollback
-
-If installation causes issues, restore your original configuration from the automatic backup:
-
-```bash
-# Interactive rollback with confirmation
-./rollback.sh
-
-# Automatic rollback without prompts
-./rollback.sh -y
 
-# Preview changes without applying
-./rollback.sh --dry-run
+# Set your git identity
+cp .gitconfig.local.example ~/.gitconfig.local
+vim ~/.gitconfig.local  # Add name, email, GPG key
 ```
 
-The rollback script:
-- Finds the latest backup directory (`.dotfiles_backup_*`)
-- Removes current dotfiles symlinks
-- Restores original files with preserved permissions
-- Cleans up the empty backup directory
-
-## Post-Install Setup
-
-### Git User Configuration
-
-The dotfiles include a shared `.gitconfig` but require you to set your personal information:
+## Daily Usage
 
 ```bash
-# Copy the example template
-cp ~/.dotfiles/.gitconfig.local.example ~/.gitconfig.local
-
-# Edit with your information
-vim ~/.gitconfig.local
-# Set: name, email, and optionally GPG signingkey
-```
+# Edit dotfiles (auto-tracked via symlinks)
+ez              # Edit .zshrc
+vim ~/.dotfiles/.aliases
+git -C ~/.dotfiles add . && git -C ~/.dotfiles commit -m "update" && git -C ~/.dotfiles push
 
-This keeps your personal information private and out of the tracked repository.
-
-## What's Included
-
-- **Zsh** - Vi mode, starship prompt, fzf, auto-detects distro
-- **Tmux** - Backtick prefix, vim navigation, session persistence
-- **Neovim** - Gruvbox theme, git integration, FZF, linting
-- **Git** - Delta pager, shortcuts (gs, ga, gc, etc.)
-- **Bookmarks** - Quick navigation (cf → ~/.config, sc → ~/.local/bin)
-
-## Key Features
-
-- **Symlink-based** - Edit once, auto-tracked in git
-- **Distro-aware** - Debian (apt) and Arch (pacman) aliases
-- **Tmux ready** - Persistent sessions survive SSH disconnects
-- **Vi everywhere** - Consistent keybindings across zsh/tmux/vim
-
-## Development & Testing
+# Sync on other machines
+git -C ~/.dotfiles pull
 
-### Automated CI Testing
+# Tmux sessions
+ts project      # New session
+` d             # Detach (backtick + d)
+ta project      # Re-attach
 
-Every pull request automatically runs:
-- **ShellCheck** - Linting for shell scripts
-- **shfmt** - Shell formatting validation
-- **Installation Test** - Verifies install.sh creates all required symlinks (~30 seconds)
+# Rollback if needed
+./rollback.sh   # Interactive restore from backup
+```
 
-### Quick Testing (30 seconds)
+## Testing
 
 ```bash
-# Run automated Docker tests
+# Quick Docker test (30s)
 ./tests/docker-test.sh
 
-# Interactive shell for debugging
+# Interactive debugging
 ./tests/docker-test.sh --interactive
 
-# Run comprehensive test suite standalone
-./tests/installation-test.sh
-```
-
-**Comprehensive test coverage includes:**
-1. **Symlink verification** - All expected dotfiles properly linked
-2. **Symlink target validation** - Links point to correct source files
-3. **ZDOTDIR compliance** - .zshrc correctly placed in XDG directory
-4. **Conditional file handling** - Optional files (.gitconfig, inputrc) tested
-5. **Idempotency** - Running install.sh twice produces identical results
-6. **Backup functionality** - Existing files safely backed up before linking
-7. **Rollback functionality** - Restoration from backup with permission preservation
-8. **Shortcut generation** - Bookmark shortcuts created from bookmarks file
-9. **Environment isolation** - Tests run in clean environment
-10. **Performance regression** - Install completes within 30-second threshold
-
-All tests include detailed diagnostics and colored output for easy debugging.
-
-### Full Integration Testing
-
-For comprehensive VM-based testing, see the [vm-infra repository](https://github.com/maxrantil/vm-infra).
-
-```bash
-# Test with local dotfiles (from vm-infra repo)
+# VM integration test (5min, from vm-infra repo)
 ./provision-vm.sh test-vm --test-dotfiles ../dotfiles
 ```
 
-### Maintaining CI Tests
-
-When modifying `install.sh`:
-
-**Adding critical symlinks** (required for shell function):
-1. Add symlink creation to `install.sh`
-2. Update `.github/workflows/shell-quality.yml` verification step
-3. Document why it's critical in workflow comments
-
-**Adding optional symlinks** (enhancements):
-1. Add symlink creation to `install.sh`
-2. No CI update needed (tested in VM tier)
-3. Document as optional in workflow comments
-
-**Critical vs Optional:**
-- **Critical**: Shell won't function without it (.zshrc, .aliases, nvim, tmux, starship)
-- **Optional**: Nice-to-have enhancements (.gitconfig, .zprofile, inputrc, shortcuts)
-
-### Troubleshooting Installation Test Failures
-
-**CI Error: "ERROR: .zshrc not linked"**
-- **Cause**: install.sh failed to create expected symlink
-- **Debug**: Run `bash install.sh` in clean test directory
-- **Check**: Verify source file exists in repository
-
-**CI Error: "ERROR: Found broken symlinks"**
-- **Cause**: Symlink points to non-existent file
-- **Debug**: Check if target file was renamed/removed in recent commits
-- **Fix**: Update install.sh symlink path or restore missing file
-
-## Usage
-
-```bash
-# Update dotfiles
-cd ~/.dotfiles
-vim .aliases
-git add . && git commit -m "update" && git push
-
-# Sync on other machines
-cd ~/.dotfiles && git pull
-```
-
-## Tmux Quick Start
+**CI automatically runs:** ShellCheck, shfmt, installation tests on every PR.
 
-```bash
-ts project        # New session
-` d               # Detach (backtick + d)
-ta project        # Re-attach
-```
+## Key Features
 
-Symlinks keep everything in sync. No reinstall needed.
+- **Fast** - <100ms shell startup with prompt caching
+- **Secure** - Pre-commit hooks (shellcheck, shfmt, gitleaks)
+- **Vi everywhere** - Consistent keybindings (zsh/tmux/vim)
+- **Tmux ready** - Sessions persist through SSH disconnects
+- **XDG compliant** - .zshrc lives in $XDG_CONFIG_HOME/zsh
 
 ## Troubleshooting
 
-Having issues? See the [Troubleshooting Guide](TROUBLESHOOTING.md) for solutions to common problems.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues and solutions.
 
 ---
 
-_Last updated: 2025-11-04_
+_Minimal by design. Personal use only._
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index 9401249..2eb5319 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -1,549 +1,180 @@
-# Troubleshooting Guide
+# Troubleshooting
 
-This guide covers common issues and their solutions for the dotfiles repository.
+Quick fixes for common issues.
 
-## Table of Contents
+## Installation
 
-1. [Installation Issues](#installation-issues)
-2. [Shell Issues](#shell-issues)
-3. [Tmux Issues](#tmux-issues)
-4. [Neovim Issues](#neovim-issues)
-5. [Git Issues](#git-issues)
-6. [Bookmark Issues](#bookmark-issues)
-7. [FZF Issues](#fzf-issues)
-8. [Performance Issues](#performance-issues)
-9. [General Debugging](#general-debugging)
-
----
-
-## Installation Issues
-
-### Problem: `./install.sh` shows "Permission denied"
-
-**Solution:**
+**Permission denied:**
 ```bash
-chmod +x ~/.dotfiles/install.sh
-./install.sh
+chmod +x ~/.dotfiles/install.sh && ./install.sh
 ```
 
-### Problem: Installation fails with "ln: failed to create symbolic link"
-
-**Cause:** Target files already exist and weren't backed up properly.
-
-**Solution:**
+**Symlink creation fails:**
 ```bash
-# Manually backup existing files
+# Manually backup and retry
 mkdir -p ~/.dotfiles-backup
-mv ~/.zshrc ~/.dotfiles-backup/
-mv ~/.tmux.conf ~/.dotfiles-backup/
-mv ~/.aliases ~/.dotfiles-backup/
-
-# Re-run installation
-cd ~/.dotfiles
-./install.sh
+mv ~/.zshrc ~/.tmux.conf ~/.aliases ~/.dotfiles-backup/
+cd ~/.dotfiles && ./install.sh
 ```
 
-### Problem: "command not found: git" during clone
-
-**Cause:** Git not installed on system.
-
-**Solution:**
-```bash
-# Debian/Ubuntu
-sudo apt-get update && sudo apt-get install -y git
-
-# Arch Linux
-sudo pacman -S git
-```
-
-### Problem: Install succeeds but configs don't load
-
-**Cause:** Shell not restarted or wrong shell active.
-
-**Solution:**
+**Configs don't load after install:**
 ```bash
-# Check current shell
-echo $SHELL
+# Verify shell
+echo $SHELL  # Should be /bin/zsh or /usr/bin/zsh
 
-# If not zsh, set as default
+# Switch if needed
 chsh -s $(which zsh)
-
-# Logout and login again, or:
 exec zsh
 ```
 
----
-
 ## Shell Issues
 
-### Problem: Zsh configuration not loading
-
-**Symptoms:** No custom prompt, aliases don't work, vi-mode missing.
-
-**Solution:**
+**Zsh config not loading:**
 ```bash
-# 1. Verify .zshrc is linked correctly
-ls -la ~/.zshrc
-# Should show: .zshrc -> /path/to/.dotfiles/.zshrc
+# Check symlink
+ls -la ~/.zshrc  # Should point to ~/.dotfiles/.zshrc
 
-# 2. Manually source to check for errors
-source ~/.zshrc
-
-# 3. Check for syntax errors
+# Test for errors
 zsh -n ~/.zshrc
+source ~/.zshrc
 
-# 4. Reload shell
-exec zsh
-```
-
-**Reference:** `.zshrc` (main configuration file)
-
-### Problem: Vi-mode not working in zsh
-
-**Symptoms:** Escape key doesn't enter normal mode, can't use vim motions.
-
-**Solution:**
-```bash
-# 1. Verify vi-mode is enabled
-grep "bindkey -v" ~/.zshrc
-
-# 2. Check key timeout (should be low for responsive mode switching)
-grep "KEYTIMEOUT" ~/.zshrc
-
-# 3. Test manually
-bindkey -v
+# Verify XDG path
+echo $ZDOTDIR  # Should be ~/.config/zsh or empty
 ```
 
-**Reference:** `.zshrc:14` (vi-mode configuration)
-
-### Problem: Prompt not showing or showing wrong information
-
-**Cause:** Starship not installed or not in PATH.
-
-**Solution:**
+**Starship prompt missing:**
 ```bash
-# 1. Check if starship is installed
-command -v starship
+# Install starship
+curl -sS https://starship.rs/install.sh | sh
 
-# 2. If not found, install starship
-# Via cargo (recommended):
-cargo install starship
-
-# Via package manager:
-# Debian/Ubuntu: Download from https://starship.rs
+# Or via package manager
 # Arch: pacman -S starship
+# Debian: download from https://starship.rs
 
-# 3. Verify starship cache exists
+# Verify cache exists
 ls -la ~/.cache/starship/
-
-# 4. Reload configuration
-source ~/.zshrc
 ```
 
-**Reference:** `.zshrc:10` (starship initialization), `starship.toml` (prompt configuration)
-
-### Problem: Distro-specific aliases not loading
-
-**Symptoms:** Package manager aliases missing (e.g., `i`, `s`, `up`).
-
-**Solution:**
+**Distro aliases not working:**
 ```bash
-# 1. Check distro detection
-cat ~/.cache/zsh/distro
-
-# 2. If wrong or missing, regenerate
-rm ~/.cache/zsh/distro
-source ~/.zshrc
+# Check detection
+cat ~/.cache/zsh/distro  # Should show "debian" or "arch"
 
-# 3. Verify distro files exist
-ls -la ~/.dotfiles/distro/debian/.aliases_debian
-ls -la ~/.dotfiles/distro/arch/.aliases_arch
-
-# 4. Check if correct file is sourced
-grep "aliases_debian\|aliases_arch" ~/.zshrc
+# Regenerate if wrong
+rm ~/.cache/zsh/distro && source ~/.zshrc
 ```
 
-**Reference:** `.zshrc:99-109` (distro detection and loading)
-
----
-
-## Tmux Issues
-
-### Problem: Tmux plugins not working
-
-**Cause:** TPM (Tmux Plugin Manager) not installed.
-
-**Solution:**
+**Bookmark shortcuts not found:**
 ```bash
-# 1. Install TPM
-git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
+# Regenerate shortcuts
+cd ~/.dotfiles && ./generate-shortcuts.sh
 
-# 2. Start tmux
-tmux
-
-# 3. Install plugins (inside tmux)
-# Press: ` + I (backtick, then capital I)
+# Verify output
+ls -la ~/.config/shell/shortcuts
 
-# 4. Verify plugins loaded
-ls -la ~/.tmux/plugins/
+# Reload
+source ~/.zshrc
 ```
 
-**Reference:** `.tmux.conf:59-65` (plugin configuration)
-
-### Problem: Colors look wrong in tmux
+## Tmux
 
-**Cause:** Terminal not reporting 256-color support.
-
-**Solution:**
+**Backtick prefix not working:**
 ```bash
-# 1. Check color support outside tmux
-echo $TERM
-# Should be: xterm-256color or similar
-
-# 2. Start tmux with correct TERM
-tmux -2
-
-# 3. Inside tmux, verify colors
-echo $TERM
-# Should be: screen-256color or tmux-256color
+# Reload config
+tmux source-file ~/.tmux.conf
 
-# 4. Add to .zshrc if needed:
-export TERM=xterm-256color
+# Or use default prefix temporarily
+# Ctrl+B, then : (colon), then type: source-file ~/.tmux.conf
 ```
 
-**Reference:** `.tmux.conf:1` (default terminal setting)
-
-### Problem: Backtick prefix not working
-
-**Symptoms:** Can't use tmux commands with ` (backtick).
-
-**Solution:**
+**Colors look wrong:**
 ```bash
-# 1. Verify prefix is set
-tmux show-options -g prefix
-# Should show: prefix `
+# Check TERM outside tmux
+echo $TERM  # Should be xterm-256color
 
-# 2. If wrong, reload tmux config
-tmux source-file ~/.tmux.conf
+# Start tmux with color support
+tmux -2
 
-# 3. Alternative: use default Ctrl+B temporarily
-# Press: Ctrl+B, then : (colon)
-# Type: source-file ~/.tmux.conf
+# Inside tmux, verify
+echo $TERM  # Should be screen-256color or tmux-256color
 ```
 
-**Reference:** `.tmux.conf:4` (prefix configuration)
-
-### Problem: Tmux sessions not persisting
-
-**Cause:** tmux-resurrect plugin not installed or not working.
-
-**Solution:**
+**Plugins not working:**
 ```bash
-# 1. Verify plugin is listed
-grep "resurrect" ~/.tmux.conf
-
-# 2. Install plugins (see "Tmux plugins not working" above)
-
-# 3. Save session manually
-# Inside tmux: ` + Ctrl+s
-
-# 4. Restore session
-# Inside tmux: ` + Ctrl+r
+# Install TPM
+git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
 
-# 5. Check saved sessions
-ls -la ~/.tmux/resurrect/
+# Inside tmux, press: ` + I (capital I)
 ```
 
-**Reference:** `.tmux.conf:60` (tmux-resurrect plugin)
+## Neovim
 
----
-
-## Neovim Issues
-
-### Problem: Neovim plugins missing
-
-**Cause:** vim-plug not installed or plugins not installed.
-
-**Solution:**
+**Plugins missing:**
 ```bash
-# 1. Check if vim-plug exists
-ls -la ~/.config/nvim/autoload/plug.vim
-
-# 2. If missing, init.vim should auto-download on first run
+# Auto-install vim-plug and plugins
 nvim +PlugInstall +qall
 
-# 3. Manually install vim-plug if needed
+# Or manually install vim-plug first
 curl -fLo ~/.config/nvim/autoload/plug.vim --create-dirs \
     https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
-
-# 4. Install plugins
-nvim +PlugInstall +qall
 ```
 
-**Reference:** `init.vim:9-11` (vim-plug auto-installation)
-
-### Problem: vim-plug shows errors
-
-**Symptoms:** PlugInstall fails, plugins won't download.
-
-**Solution:**
+**Colorscheme broken:**
 ```bash
-# 1. Check internet connectivity
-curl -I https://github.com
-
-# 2. Clean plugin directory
-rm -rf ~/.config/nvim/plugged/*
-
-# 3. Reinstall plugins
+# Reinstall gruvbox
 nvim +PlugInstall +qall
 
-# 4. Check for specific plugin errors
-nvim +checkhealth
+# Check terminal colors (see Tmux section above)
 ```
 
-**Reference:** `init.vim:16-23` (plugin definitions)
-
-### Problem: Gruvbox colorscheme not working
-
-**Cause:** Plugin not installed or terminal doesn't support colors.
+## Git
 
-**Solution:**
+**Delta pager not working:**
 ```bash
-# 1. Verify gruvbox plugin installed
-ls -la ~/.config/nvim/plugged/gruvbox/
-
-# 2. Install if missing
-nvim +PlugInstall +qall
-
-# 3. Check terminal colors (see Tmux color issues above)
-
-# 4. Force gruvbox in init.vim
-nvim ~/.config/nvim/init.vim
-# Verify line: colorscheme gruvbox
-```
-
-**Reference:** `init.vim:17` (gruvbox plugin), `init.vim:26` (colorscheme activation)
-
----
-
-## Git Issues
-
-### Problem: Delta pager not working
-
-**Symptoms:** Git diff shows plain text without syntax highlighting.
-
-**Cause:** Delta not installed or not in PATH.
-
-**Solution:**
-```bash
-# 1. Check if delta is installed
-command -v delta
-
-# 2. Install delta
-# Via cargo:
+# Install delta
 cargo install git-delta
 
-# Via package manager:
-# Debian/Ubuntu: Download from https://github.com/dandavison/delta/releases
+# Or via package manager
 # Arch: pacman -S git-delta
+# Debian: download from https://github.com/dandavison/delta/releases
 
-# 3. Verify git config
-git config --get core.pager
-# Should show: delta
-
-# 4. Test delta
-git diff
-```
-
-**Reference:** `.gitconfig:2-3` (delta pager configuration)
-
-### Problem: Git aliases not working
-
-**Symptoms:** Commands like `gs`, `ga`, `gc` show "command not found".
-
-**Solution:**
-```bash
-# 1. Verify .gitconfig is linked
-ls -la ~/.gitconfig
-# Should show: .gitconfig -> /path/to/.dotfiles/.gitconfig
-
-# 2. Check git config loaded
-git config --get alias.s
-# Should show: status
-
-# 3. If not linked, reinstall
-cd ~/.dotfiles
-./install.sh
-
-# 4. Test aliases
-git s  # Should run git status
-```
-
-**Reference:** `.gitconfig:7-32` (git alias definitions)
-
-### Problem: Git colors not showing
-
-**Cause:** Color support disabled in git config.
-
-**Solution:**
-```bash
-# 1. Enable colors
-git config --global color.ui auto
-
-# 2. Verify delta configuration
-git config --list | grep delta
-
-# 3. Check terminal colors (see Tmux section above)
-```
-
-**Reference:** `.gitconfig:34-48` (delta color configuration)
-
----
-
-## Bookmark Issues
-
-### Problem: Bookmark shortcuts not working
-
-**Symptoms:** Commands like `cf`, `sc`, `dt` show "command not found".
-
-**Cause:** Shortcuts not generated or not sourced.
-
-**Solution:**
-```bash
-# 1. Generate shortcuts
-cd ~/.dotfiles
-./generate-shortcuts.sh
-
-# 2. Verify output file exists
-ls -la ~/.config/shell/shortcuts
-
-# 3. Check if sourced in .zshrc
-grep "shortcuts" ~/.zshrc
-
-# 4. Manually source
-source ~/.config/shell/shortcuts
-
-# 5. Reload shell
-source ~/.zshrc
+# Verify config
+git config --get core.pager  # Should show "delta"
 ```
 
-**Reference:** `generate-shortcuts.sh` (shortcut generator), `.zshrc:95` (shortcuts sourcing)
-
-### Problem: Bookmark paths are wrong
-
-**Cause:** Paths in `bm-files` or `bm-dirs` don't match actual file locations.
-
-**Solution:**
+**Git aliases not working:**
 ```bash
-# 1. Edit bookmark files
-vim ~/.dotfiles/bm-files
-vim ~/.dotfiles/bm-dirs
-
-# 2. Update paths to actual locations
-# Example:
-# cfz  ~/.dotfiles/.aliases  # Not ~/.config/shell/aliasrc
-
-# 3. Regenerate shortcuts
-cd ~/.dotfiles
-./generate-shortcuts.sh
-
-# 4. Reload shell
-source ~/.zshrc
-```
-
-**Reference:** `bm-files`, `bm-dirs` (bookmark definitions)
-
-### Problem: Changes to bookmarks don't take effect
-
-**Cause:** Shortcuts not regenerated after editing bookmark files.
-
-**Solution:**
-```bash
-# Always regenerate after editing bookmarks
-cd ~/.dotfiles
-vim bm-files  # Make changes
-./generate-shortcuts.sh  # Regenerate
-source ~/.zshrc  # Reload
-```
-
-**Reference:** `generate-shortcuts.sh:13` (bookmark processing)
-
----
-
-## FZF Issues
-
-### Problem: Ctrl+R history search not working
-
-**Cause:** FZF not installed or keybinding not loaded.
-
-**Solution:**
-```bash
-# 1. Check if fzf is installed
-command -v fzf
-
-# 2. Install fzf
-git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
-~/.fzf/install
-
-# 3. Verify fzf.zsh exists and is sourced
-ls -la ~/.fzf.zsh
-grep "fzf.zsh" ~/.zshrc
+# Verify symlink
+ls -la ~/.gitconfig  # Should point to ~/.dotfiles/.gitconfig
 
-# 4. Reload shell
-source ~/.zshrc
+# Test specific alias
+git config --get alias.s  # Should show "status"
 
-# 5. Test Ctrl+R
-# Press Ctrl+R and start typing
+# Reinstall if broken
+cd ~/.dotfiles && ./install.sh
 ```
 
-**Reference:** `.zshrc:91` (fzf sourcing)
-
-### Problem: FZF preview not showing in functions
-
-**Symptoms:** `ff` function doesn't show file preview.
+## Performance
 
-**Cause:** Preview command failing or bat/cat not available.
-
-**Solution:**
+**Measure startup time:**
 ```bash
-# 1. Test preview manually
-fzf --preview 'cat {}'
-
-# 2. Install bat for better previews (optional)
-# Debian/Ubuntu:
-sudo apt-get install bat
-# Arch:
-sudo pacman -S bat
-
-# 3. Update ff function to use bat
-vim ~/.dotfiles/.aliases
-# Change: --preview 'cat {}' to --preview 'bat --color=always {}'
-```
-
-**Reference:** `.aliases:43` (ff function definition)
-
----
-
-## Performance Issues
-
-### Problem: Shell startup is slow (>1 second)
-
-**Symptoms:** Noticeable delay when opening new terminal.
-
-**Diagnostic:**
-```bash
-# Measure startup time
 time zsh -i -c exit
+# Target: <100ms
 
-# Profile startup to find bottlenecks
+# Profile to find bottlenecks
 zsh -i -c 'zmodload zsh/zprof; source ~/.zshrc; zprof'
 ```
 
-**Solutions:**
-
-**1. Enable compinit caching:**
+**Slow startup fixes:**
 ```bash
-# Add to .zshrc before compinit call:
+# 1. Verify starship cache exists
+ls -la ~/.cache/starship/
+
+# 2. Check distro detection cache
+cat ~/.cache/zsh/distro
+
+# 3. Enable compinit caching (if not already)
+# Add to .zshrc before compinit:
 autoload -U compinit
 if [[ -n ${ZDOTDIR:-$HOME}/.zcompdump(#qN.mh+24) ]]; then
     compinit
@@ -551,255 +182,104 @@ else
     compinit -C
 fi
 ```
-**Impact:** 100-200ms improvement
-
-**2. Verify starship caching is enabled:**
-```bash
-# Check cache directory
-ls -la ~/.cache/starship/
-
-# Regenerate if needed
-rm -rf ~/.cache/starship/
-source ~/.zshrc
-```
-**Reference:** `.zshrc:10` (starship caching)
-
-**Impact:** 50-100ms improvement
-
-**3. Check distro detection caching:**
-```bash
-# Verify cache exists
-cat ~/.cache/zsh/distro
-
-# Should contain: debian or arch
-# If missing, it regenerates on every startup
-```
-**Reference:** `.zshrc:99-109` (distro caching)
 
-**Impact:** 20-30ms improvement
-
-**4. Lazy-load heavy tools (NVM, if installed):**
+**Tmux sluggish:**
 ```bash
-# If you have NVM installed, it can slow startup by 200-400ms
-# Consider lazy loading (beyond scope of default config)
-```
-
-### Problem: Tmux feels sluggish
-
-**Cause:** Too many plugins or escape-time too high.
-
-**Solution:**
-```bash
-# 1. Check escape time
+# Check escape time (should be 0)
 tmux show-options -g escape-time
-# Should be: 0 or very low
 
-# 2. Reduce if needed
+# Reduce if needed
 echo "set -sg escape-time 0" >> ~/.tmux.conf
 tmux source-file ~/.tmux.conf
-
-# 3. Disable unnecessary plugins
-vim ~/.tmux.conf
-# Comment out plugins you don't use
 ```
 
-**Reference:** `.tmux.conf:14` (escape-time configuration)
+## Debugging
 
-### Problem: Git operations are slow
-
-**Cause:** Delta processing large diffs or repository issues.
-
-**Solution:**
+**Find problematic config:**
 ```bash
-# 1. Disable delta temporarily for large repos
-git config --local core.pager less
-
-# 2. Or increase delta performance
-git config --global delta.max-line-length 1024
-
-# 3. Check repository health
-git fsck
-git gc
-```
-
----
-
-## General Debugging
-
-### How to find which config file is causing issues
-
-**Method 1: Binary search**
-```bash
-# 1. Comment out half of .zshrc
+# Binary search: comment out half of .zshrc, reload, repeat
 vim ~/.zshrc
-# Comment lines and reload:
 source ~/.zshrc
 
-# 2. If issue persists, problem is in other half
-# If issue disappears, problem is in commented section
-# Repeat until isolated
-```
-
-**Method 2: Start with minimal config**
-```bash
-# 1. Temporarily rename configs
+# Or start minimal
 mv ~/.zshrc ~/.zshrc.backup
-mv ~/.zprofile ~/.zprofile.backup
-
-# 2. Create minimal .zshrc
-echo "# Minimal test" > ~/.zshrc
-
-# 3. Add back sections one at a time
-# Test after each addition:
-source ~/.zshrc
-```
-
-### How to check if files are properly linked
-
-```bash
-# Verify all symlinks
-ls -la ~/.zshrc ~/.tmux.conf ~/.aliases ~/.gitconfig ~/.zprofile
-
-# Should all show: file -> /path/to/.dotfiles/file
-
-# If not linked, reinstall
-cd ~/.dotfiles
-./install.sh
+echo "# Test" > ~/.zshrc
+# Add sections back one at a time
 ```
 
-### How to completely reset dotfiles
-
+**Check syntax errors:**
 ```bash
-# 1. Backup current state
-mkdir -p ~/dotfiles-backup-$(date +%Y%m%d)
-cp -r ~/.dotfiles ~/dotfiles-backup-$(date +%Y%m%d)/
-
-# 2. Remove symlinks
-rm -f ~/.zshrc ~/.tmux.conf ~/.aliases ~/.gitconfig ~/.zprofile
-rm -f ~/.config/nvim/init.vim
-
-# 3. Remove dotfiles directory
-rm -rf ~/.dotfiles
-
-# 4. Fresh install
-git clone https://github.com/maxrantil/dotfiles.git ~/.dotfiles
-cd ~/.dotfiles
-./install.sh
-
-# 5. Restart shell
-exec zsh
-```
-
-### How to check for syntax errors
-
-```bash
-# Zsh configs
+# Zsh
 zsh -n ~/.zshrc
 zsh -n ~/.zprofile
 zsh -n ~/.dotfiles/.aliases
 
 # Shell scripts
 bash -n ~/.dotfiles/install.sh
-bash -n ~/.dotfiles/generate-shortcuts.sh
 
-# Tmux config
+# Tmux
 tmux source-file ~/.tmux.conf
-# Will show errors if any
 
-# Neovim config
+# Neovim
 nvim +checkhealth
 ```
 
-### How to enable verbose logging
+**Verify symlinks:**
+```bash
+ls -la ~/.zshrc ~/.tmux.conf ~/.aliases ~/.gitconfig ~/.zprofile
+# All should point to ~/.dotfiles/[file]
+
+# Reinstall if broken
+cd ~/.dotfiles && ./install.sh
+```
 
+**Verbose debugging:**
 ```bash
-# Zsh startup debugging
+# Zsh startup trace
 zsh -xv ~/.zshrc 2>&1 | less
-# Shows every command executed during startup
 
-# Tmux debugging
+# Tmux verbose
 tmux -vv
-# Shows verbose output
 
-# Git debugging
+# Git trace
 GIT_TRACE=1 git status
-# Shows git internals
 ```
 
-### Where to find log files
+## Complete Reset
 
 ```bash
-# Zsh history
-~/.cache/zsh/history
-
-# Tmux resurrect saves
-~/.tmux/resurrect/
+# 1. Backup
+mkdir -p ~/dotfiles-backup-$(date +%Y%m%d)
+cp -r ~/.dotfiles ~/dotfiles-backup-$(date +%Y%m%d)/
 
-# Neovim plugin logs
-~/.local/share/nvim/
+# 2. Remove everything
+rm -f ~/.zshrc ~/.tmux.conf ~/.aliases ~/.gitconfig ~/.zprofile
+rm -f ~/.config/nvim/init.vim
+rm -rf ~/.dotfiles
 
-# Starship cache
-~/.cache/starship/
+# 3. Fresh install
+git clone https://github.com/maxrantil/dotfiles.git ~/.dotfiles
+cd ~/.dotfiles && ./install.sh
 
-# General shell cache
-~/.cache/zsh/
+# 4. Restart
+exec zsh
 ```
 
----
-
-## Getting Additional Help
-
-If you've tried the solutions above and still have issues:
-
-1. **Check Prerequisites:**
-   - Verify all required tools are installed: zsh, tmux, neovim, git, fzf
-   - Ensure you have write access to `$HOME` directory
-   - Confirm your terminal supports 256 colors
-
-2. **Run Docker Tests:**
-   ```bash
-   cd ~/.dotfiles
-   ./tests/docker-test.sh
-   ```
-   This validates the dotfiles in a clean environment.
-
-3. **Review Recent Changes:**
-   ```bash
-   cd ~/.dotfiles
-   git log --oneline -10
-   git diff HEAD~1
-   ```
-   Recent changes might have introduced issues.
-
-4. **Create GitHub Issue:**
-   Visit https://github.com/maxrantil/dotfiles/issues and provide:
-   - Output of `uname -a` (system info)
-   - Output of `zsh --version`
-   - Output of `time zsh -i -c exit` (startup time)
-   - Error messages (full output)
-   - Steps to reproduce
+## Quick Reference
 
----
+**Reload configs:**
+- `source ~/.zshrc` or `exec zsh`
+- `tmux source-file ~/.tmux.conf`
 
-## Quick Reference
+**Test environment:**
+- `cd ~/.dotfiles && ./tests/docker-test.sh`
 
-**Essential Commands:**
-- Reload zsh: `source ~/.zshrc` or `exec zsh`
-- Reload tmux: `tmux source-file ~/.tmux.conf`
-- Reinstall dotfiles: `cd ~/.dotfiles && ./install.sh`
-- Run tests: `cd ~/.dotfiles && ./tests/docker-test.sh`
-
-**Key Files:**
-- `.zshrc` - Main shell configuration
-- `.zprofile` - Shell environment variables
-- `.aliases` - Shared aliases and functions
-- `.tmux.conf` - Tmux configuration
-- `init.vim` - Neovim configuration
-- `.gitconfig` - Git configuration
-- `starship.toml` - Prompt configuration
-
-**Cache Locations:**
+**Key cache locations:**
 - Zsh: `~/.cache/zsh/`
 - Starship: `~/.cache/starship/`
 - Tmux plugins: `~/.tmux/plugins/`
 - Neovim plugins: `~/.config/nvim/plugged/`
+
+---
+
+_Most issues are fixed by: `cd ~/.dotfiles && ./install.sh && exec zsh`_