Dotfiles update 2025-12-24 17:46

2025-12-24 17:46:07 -05:00
parent b12a5a7b0f
commit e86371e63a
10 changed files with 1665 additions and 4111 deletions
--- a/docs/REFERENCE.md
+++ b/docs/REFERENCE.md
@@ -0,0 +1,608 @@
+# Reference Guide
+
+Complete reference for ADLee's Dotfiles configuration, Espanso triggers, and advanced features.
+
+## Table of Contents
+
+- [Configuration Reference](#configuration-reference)
+- [Espanso Triggers](#espanso-triggers)
+- [Vim Configuration](#vim-configuration)
+- [Tmux Configuration](#tmux-configuration)
+- [Git Aliases](#git-aliases)
+- [Function Files Reference](#function-files-reference)
+- [Color Reference](#color-reference)
+
+---
+
+## Configuration Reference
+
+### dotfiles.conf Options
+
+Complete list of all configuration options in `~/.dotfiles/dotfiles.conf`:
+
+#### Core Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DOTFILES_VERSION` | `"1.2.0"` | Dotfiles version |
+| `DOTFILES_DIR` | `"$HOME/.dotfiles"` | Installation directory |
+| `DOTFILES_BRANCH` | `"main"` | Git branch to use |
+| `DOTFILES_BACKUP_PREFIX` | `"$HOME/.dotfiles_backup"` | Backup location prefix |
+
+#### GitHub Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DOTFILES_GITHUB_USER` | `"adlee-was-taken"` | GitHub username |
+| `DOTFILES_REPO_NAME` | `"dotfiles"` | Repository name |
+
+#### User Identity
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `USER_FULLNAME` | `""` | Your full name |
+| `USER_EMAIL` | `""` | Your email |
+| `USER_GITHUB` | `""` | Your GitHub username |
+
+#### Git Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_USER_NAME` | `""` | Git user.name (falls back to USER_FULLNAME) |
+| `GIT_USER_EMAIL` | `""` | Git user.email (falls back to USER_EMAIL) |
+| `GIT_DEFAULT_BRANCH` | `"main"` | Default branch name |
+
+#### Feature Toggles
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `INSTALL_DEPS` | `auto/true/false` | Install dependencies |
+| `INSTALL_ZSH_PLUGINS` | `true/false` | Install zsh plugins |
+| `INSTALL_FZF` | `true/false/ask` | Install fzf |
+| `INSTALL_BAT` | `true/false/ask` | Install bat |
+| `INSTALL_EZA` | `true/false/ask` | Install eza |
+| `INSTALL_NEOVIM` | `true/false/ask` | Install neovim |
+| `SET_ZSH_DEFAULT` | `true/false/ask` | Set zsh as default shell |
+
+#### MOTD Settings
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `ENABLE_MOTD` | `true/false` | Enable MOTD display |
+| `MOTD_STYLE` | `compact/mini/full/none` | MOTD display style |
+| `MOTD_SHOW_FAILED_SERVICES` | `true/false` | Show failed systemd services |
+| `MOTD_SHOW_UPDATES` | `true/false` | Show available updates |
+
+#### Theme Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ZSH_THEME_NAME` | `"adlee"` | Zsh theme name |
+| `THEME_TIMER_THRESHOLD` | `10` | Seconds before showing timer |
+| `THEME_PATH_TRUNCATE_LENGTH` | `32` | Max path display length |
+
+#### Advanced Features
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ENABLE_SMART_SUGGESTIONS` | `true` | Enable typo correction |
+| `ENABLE_COMMAND_PALETTE` | `true` | Enable Ctrl+Space palette |
+| `ENABLE_SHELL_ANALYTICS` | `false` | Command usage tracking |
+| `ENABLE_VAULT` | `true` | Enable secrets vault |
+| `DOTFILES_AUTO_SYNC_CHECK` | `true` | Check for updates on start |
+
+#### Btrfs Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BTRFS_DEFAULT_MOUNT` | `"/"` | Default mount for btrfs commands |
+
+#### Snapper Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SNAPPER_CONFIG` | `"root"` | Snapper config name |
+| `LIMINE_CONF` | `"/boot/limine.conf"` | Limine config path |
+
+#### Tmux Workspace Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TW_SESSION_PREFIX` | `"work"` | Session naming prefix |
+| `TW_DEFAULT_TEMPLATE` | `"dev"` | Default workspace template |
+
+#### Python Template Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PY_TEMPLATE_BASE_DIR` | `"$HOME/projects"` | Project base directory |
+| `PY_TEMPLATE_PYTHON` | `"python3"` | Python executable |
+| `PY_TEMPLATE_VENV_NAME` | `"venv"` | Virtual env directory name |
+| `PY_TEMPLATE_USE_POETRY` | `false` | Use poetry instead of venv |
+| `PY_TEMPLATE_GIT_INIT` | `true` | Initialize git repo |
+
+#### SSH Manager Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SSH_AUTO_TMUX` | `true` | Auto-create tmux session |
+| `SSH_TMUX_SESSION_PREFIX` | `"ssh"` | Session naming prefix |
+| `SSH_SYNC_DOTFILES` | `ask` | Sync dotfiles on connect |
+
+#### Package Manager
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `AUR_HELPER` | `auto/paru/yay` | Preferred AUR helper |
+
+---
+
+## Espanso Triggers
+
+Complete list of text expansion triggers.
+
+### Date and Time
+
+| Trigger | Output | Example |
+|---------|--------|---------|
+| `..date` | Date (YYYY-MM-DD) | `2025-12-24` |
+| `..ds` | Same as `..date` | `2025-12-24` |
+| `..sds` | Short date (YYYYMMDD) | `20251224` |
+| `..time` | Time (HH:MM:SS) | `14:30:45` |
+| `..utime` | UTC time | `19:30:45` |
+| `..ztime` | Time with timezone | `14:30:45.123 EST` |
+| `..uztime` | UTC time with timezone | `19:30:45.123 UTC` |
+| `..dt` | Date + time | `2025-12-24 14:30:45 EST` |
+| `..udt` | UTC date + time | `2025-12-24 19:30:45 UTC` |
+| `..ts` | ISO 8601 timestamp | `2025-12-24T19:30:45.123Z` |
+| `..utc` | UTC with milliseconds | `2025-12-24 19:30:45.123 UTC` |
+| `..month` | Month name | `December` |
+| `..year` | Year | `2025` |
+| `..week` | Week number | `Week 52` |
+| `..day` | Day of week | `Wednesday` |
+| `..epoch` | Unix timestamp | `1735066245` |
+| `..epochms` | Unix timestamp (ms) | `1735066245123` |
+
+### Quick Text
+
+| Trigger | Output |
+|---------|--------|
+| `..shrug` | `¯\_(ツ)_/¯` |
+| `..flip` | `(╯°□°)╯︵ ┻━┻` |
+| `..unflip` | `┬─┬ ノ( ゜-゜ノ)` |
+| `..lenny` | `( ͡° ͜ʖ ͡°)` |
+| `..check` | `✓` |
+| `..cross` | `✗` |
+| `..arrow` | `→` |
+| `..larrow` | `←` |
+
+### Quick Responses
+
+| Trigger | Output |
+|---------|--------|
+| `..brb` | Be right back |
+| `..omw` | On my way |
+| `..tyvm` | Thank you very much |
+| `..lgtm` | Looks good to me |
+| `..wfm` | Works for me |
+| `..ack` | Acknowledged |
+| `..asap` | As soon as possible |
+
+### System Information
+
+| Trigger | Output |
+|---------|--------|
+| `..ip` | Public IP address |
+| `..locip` | Local IP address |
+| `..branch` | Current git branch |
+
+### Git Commands
+
+| Trigger | Output |
+|---------|--------|
+| `..gstat` | `git status` |
+| `..gco` | `git checkout ` |
+| `..gcm` | `git commit -m ""` |
+| `..glog` | `git log --oneline --graph --decorate --all` |
+| `..gpush` | `git push origin ` |
+| `..gpull` | `git pull origin ` |
+| `..gbranch` | `git branch -a` |
+| `..gdiff` | `git diff` |
+| `..gadd` | `git add .` |
+
+### Docker Commands
+
+| Trigger | Output |
+|---------|--------|
+| `..dps` | `docker ps` |
+| `..dpsa` | `docker ps -a` |
+| `..dcup` | `docker-compose up -d` |
+| `..dcdown` | `docker-compose down` |
+| `..dlog` | `docker logs -f ` |
+| `..dexec` | `docker exec -it ` |
+| `..dim` | `docker images` |
+| `..dprune` | `docker system prune -af` |
+
+### Code Templates
+
+| Trigger | Output |
+|---------|--------|
+| `..bash` | Bash shebang + `set -euo pipefail` |
+| `..python` | Python main boilerplate |
+| `..she!` | `#!/usr/bin/env bash` |
+
+### Markdown
+
+| Trigger | Output |
+|---------|--------|
+| `..mdcode` | Code block (generic) |
+| `..mdbash` | Bash code block |
+| `..mdpy` | Python code block |
+| `..mdjs` | JavaScript code block |
+| `..mdtable` | Markdown table template |
+| `..mdlink` | `[text](url)` (prompts) |
+| `..mdimg` | `![alt](url)` (prompts) |
+
+### Programming Comments
+
+| Trigger | Output |
+|---------|--------|
+| `..todo` | `// TODO: ` |
+| `..fixme` | `// FIXME: ` |
+| `..note` | `// NOTE: ` |
+| `..hack` | `// HACK: ` |
+| `..debug` | `// DEBUG: ` |
+
+### Common Commands
+
+| Trigger | Output |
+|---------|--------|
+| `..ll` | `ls -lah` |
+| `..la` | `ls -A` |
+| `..grep` | `grep -rni "" .` |
+| `..find` | `find . -name ""` |
+| `..port` | `lsof -i :` |
+| `..kill` | `kill -9 ` |
+| `..proc` | `ps aux \| grep ` |
+| `..disk` | `df -h` |
+| `..mem` | `free -h` |
+
+### Navigation
+
+| Trigger | Output |
+|---------|--------|
+| `..~` | `cd ~` |
+| `..tmp` | `cd /tmp/` |
+| `..logs` | `cd /var/log/` |
+
+### URLs
+
+| Trigger | Output |
+|---------|--------|
+| `..gh` | `https://github.com` |
+| `..gl` | `https://gitlab.com` |
+| `..gist` | `https://gist.github.com` |
+| `..so` | `https://stackoverflow.com` |
+| `..reddit` | `https://reddit.com` |
+
+### Lorem Ipsum
+
+| Trigger | Output |
+|---------|--------|
+| `..lorem` | One paragraph |
+| `..loremlong` | Four paragraphs |
+
+### Clipboard
+
+| Trigger | Output |
+|---------|--------|
+| `..qp` | Primary clipboard (X11 selection) |
+
+### Typo Corrections
+
+| Trigger | Correction |
+|---------|------------|
+| `teh` | the |
+| `recieve` | receive |
+| `seperator` | separator |
+| `definately` | definitely |
+| `occured` | occurred |
+| `lenght` | length |
+| `wierd` | weird |
+| `thier` | their |
+
+### Emoji Package
+
+| Trigger | Emoji |
+|---------|-------|
+| `:lol` | 😂 |
+| `:sad` | ☹ |
+| `:sml` | 😊 |
+| `:strong` | 💪 |
+| `:ba` | 😎 |
+| `:ok` | 👍 |
+| `:happy` | 😄 |
+| `:cry` | 😭 |
+| `:wow` | 😮 |
+
+### Personal (in personal.yml)
+
+| Trigger | Output |
+|---------|--------|
+| `..myemail` | Your email |
+| `..myname` | Your full name |
+| `..myphone` | Your phone |
+| `..myweb` | Your website |
+| `..mygithub` | Your GitHub URL |
+| `..sig` | Email signature |
+| `..sigfull` | Full signature |
+| `..myaddr` | Your address |
+| `..workemail` | Work email |
+| `..worksig` | Work signature |
+
+---
+
+## Vim Configuration
+
+### Leader Key
+
+The leader key is `,` (comma).
+
+### Key Mappings
+
+| Mapping | Action |
+|---------|--------|
+| `,w` | Fast save (`:w!`) |
+| `:W` | Sudo save |
+| `Space` | Search (`/`) |
+| `Ctrl+Space` | Backward search (`?`) |
+| `,<Enter>` | Disable search highlight |
+| `Ctrl+j/k/h/l` | Move between windows |
+| `,bd` | Close buffer |
+| `,ba` | Close all buffers |
+| `,l` / `,h` | Next/previous buffer |
+| `,tn` | New tab |
+| `,to` | Tab only |
+| `,tc` | Close tab |
+| `,tm` | Move tab |
+| `,tl` | Toggle last tab |
+| `,te` | Open tab with buffer's path |
+| `,cd` | Switch CWD to buffer dir |
+| `Alt+j/k` | Move line down/up |
+| `,ss` | Toggle spell checking |
+| `,sn` / `,sp` | Next/previous misspelling |
+| `,sa` | Add to dictionary |
+| `,s?` | Suggest corrections |
+| `,pp` | Toggle paste mode |
+| `,q` | Open scratch buffer |
+| `,x` | Open markdown buffer |
+| `0` | First non-blank character |
+
+### Settings
+
+- 4 spaces for indentation
+- Tabs expanded to spaces
+- Smart indentation
+- Line wrapping on word boundaries
+- Incremental search with highlighting
+- Wild menu for command completion
+
+---
+
+## Tmux Configuration
+
+### Key Bindings
+
+| Binding | Action |
+|---------|--------|
+| `Prefix + U` | Resize pane up 8 lines |
+| `Prefix + D` | Resize pane down 8 lines |
+| `Prefix + L` | Resize pane left 8 chars |
+| `Prefix + R` | Resize pane right 8 chars |
+
+### Settings
+
+- Default shell: `/usr/bin/zsh`
+- Terminal: `tmux-256color`
+- XTerm keys enabled
+- Escape time: 0 (no delay)
+- Pane border status: bottom
+
+---
+
+## Git Aliases
+
+Built-in git aliases from `.gitconfig`:
+
+| Alias | Command |
+|-------|---------|
+| `git st` | `git status` |
+| `git co` | `git checkout` |
+| `git br` | `git branch` |
+| `git ci` | `git commit` |
+| `git lg` | `git log --oneline --graph --decorate --all` |
+| `git unstage` | `git reset HEAD --` |
+| `git last` | `git log -1 HEAD` |
+| `git visual` | `gitk` |
+
+---
+
+## Function Files Reference
+
+### btrfs-helpers.zsh
+
+Btrfs filesystem management utilities.
+
+**Exported functions:** `btrfs-usage`, `btrfs-subs`, `btrfs-balance`, `btrfs-balance-status`, `btrfs-balance-cancel`, `btrfs-scrub`, `btrfs-scrub-status`, `btrfs-scrub-cancel`, `btrfs-defrag`, `btrfs-compress`, `btrfs-info`, `btrfs-health`, `btrfs-snap-usage`, `btrfs-maintain`, `btrfs-help`
+
+**Aliases:** `btru`, `btrs`, `btrh`, `btri`, `btrc`
+
+### command-palette.zsh
+
+Fuzzy command launcher.
+
+**Exported functions:** `command_palette`, `palette`, `p`, `bookmark`, `bm`, `jump`, `j`
+
+**Key bindings:** `Ctrl+Space`, `Ctrl+P`
+
+### motd.zsh
+
+Message of the Day display.
+
+**Exported functions:** `show_motd`, `show_motd_mini`, `show_motd_full`, `sysbrief`
+
+**Aliases:** `motd`, `motd-mini`, `motd-full`
+
+### password-manager.zsh
+
+LastPass CLI integration.
+
+**Exported functions:** `pw`, `pwf`, `pwof`
+
+**Aliases:** `pwl`, `pwg`, `pwc`, `pws`
+
+### python-templates.zsh
+
+Python project scaffolding.
+
+**Exported functions:** `py-new`, `py-django`, `py-flask`, `py-fastapi`, `py-data`, `py-cli`, `venv`
+
+**Aliases:** `pynew`, `pydjango`, `pyflask`, `pyfast`, `pydata`, `pycli`
+
+### smart-suggest.zsh
+
+Typo correction and suggestions.
+
+**Exported functions:** `command_not_found_handler`, `fuck`
+
+### snapper.zsh
+
+Btrfs snapshot management.
+
+**Exported functions:** `snap-create`, `snap-list`, `snap-show`, `snap-delete`, `snap-check-limine`, `snap-sync`, `snap-validate-service`
+
+**Aliases:** `snap`, `snapls`, `snaprm`, `snapshow`, `snapcheck`, `snapsync`
+
+### ssh-manager.zsh
+
+SSH profile management.
+
+**Exported functions:** `ssh-save`, `ssh-list`, `ssh-connect`, `ssh-delete`, `ssh-reconnect`, `ssh-sync-dotfiles`, `sshf`
+
+**Aliases:** `sshl`, `sshs`, `sshc`, `sshd`, `sshr`, `sshsync`
+
+### systemd-helpers.zsh
+
+Systemd service management.
+
+**Exported functions:** `sc`, `scu`, `scr`, `sce`, `scd`, `sclog`, `sclogs`, `sc-failed`, `sc-timers`, `sc-recent`, `sc-boot`, `sc-search`, `sc-info`, `scf`, `sclogf`, `sc-help`
+
+**Aliases:** `scs`, `scstart`, `scstop`, `screload`, `scmask`, `scunmask`, `jctl`, `jctlf`, `jctlb`, `jctlerr`
+
+### tmux-workspaces.zsh
+
+Tmux workspace management.
+
+**Exported functions:** `tw`, `tw-create`, `tw-attach`, `tw-list`, `tw-delete`, `tw-save`, `tw-templates`, `tw-template-edit`, `tw-sync`, `tw-rename`, `twf`
+
+**Aliases:** `twl`, `twc`, `twa`, `twd`, `tws`, `twt`, `twe`
+
+---
+
+## Color Reference
+
+Color variables defined in `zsh/lib/colors.zsh`:
+
+### Standard Colors
+
+| Variable | Description |
+|----------|-------------|
+| `DF_RED` | Red |
+| `DF_GREEN` | Green |
+| `DF_YELLOW` | Yellow (bold) |
+| `DF_BLUE` | Blue |
+| `DF_MAGENTA` | Magenta |
+| `DF_CYAN` | Cyan |
+| `DF_WHITE` | White |
+
+### Bold Variants
+
+`DF_BOLD_RED`, `DF_BOLD_GREEN`, `DF_BOLD_YELLOW`, `DF_BOLD_BLUE`, `DF_BOLD_MAGENTA`, `DF_BOLD_CYAN`, `DF_BOLD_WHITE`
+
+### Text Styles
+
+| Variable | Description |
+|----------|-------------|
+| `DF_BOLD` | Bold text |
+| `DF_DIM` | Dim/faint text |
+| `DF_ITALIC` | Italic text |
+| `DF_UNDERLINE` | Underlined text |
+| `DF_RESET` / `DF_NC` | Reset formatting |
+
+### 256-Color Palette
+
+| Variable | Description |
+|----------|-------------|
+| `DF_GREY` | Grey (242) |
+| `DF_LIGHT_GREY` | Light grey (248) |
+| `DF_DARK_GREY` | Dark grey (239) |
+| `DF_ORANGE` | Orange (208) |
+| `DF_LIGHT_ORANGE` | Light orange (220) |
+| `DF_PINK` | Pink (213) |
+| `DF_PURPLE` | Purple (141) |
+| `DF_LIGHT_BLUE` | Light blue (39) |
+| `DF_LIGHT_GREEN` | Light green (82) |
+| `DF_BRIGHT_GREEN` | Bright green (118) |
+| `DF_TEAL` | Teal (51) |
+
+### Semantic Colors
+
+| Variable | Maps To |
+|----------|---------|
+| `DF_SUCCESS` | `DF_GREEN` |
+| `DF_ERROR` | `DF_RED` |
+| `DF_WARNING` | `DF_YELLOW` |
+| `DF_INFO` | `DF_CYAN` |
+| `DF_HINT` | `DF_DIM` |
+| `DF_ACCENT` | `DF_BLUE` |
+| `DF_MUTED` | `DF_GREY` |
+
+### Print Functions
+
+| Function | Description |
+|----------|-------------|
+| `df_print_step "msg"` | Print step with `==>` prefix |
+| `df_print_success "msg"` | Print with ✓ prefix |
+| `df_print_error "msg"` | Print with ✗ prefix (stderr) |
+| `df_print_warning "msg"` | Print with ⚠ prefix |
+| `df_print_info "msg"` | Print with ℹ prefix |
+| `df_print_section "title"` | Print section divider |
+| `df_print_header "name"` | Print MOTD-style header box |
+
+### Usage in Scripts
+
+```bash
+# In bash scripts
+source "$HOME/.dotfiles/zsh/lib/colors.zsh"
+echo -e "${DF_GREEN}Success!${DF_NC}"
+
+# In zsh functions
+source "${0:A:h}/../lib/colors.zsh"
+df_print_success "Operation completed"
+```
+
+---
+
+## Environment Variables
+
+These are set or used by the dotfiles:
+
+| Variable | Description |
+|----------|-------------|
+| `DOTFILES_DIR` | Dotfiles installation path |
+| `UPDATE_PKG_COUNT` | Available package updates (for prompt) |
+| `EDITOR` | Default editor (vim) |
+| `VISUAL` | Visual editor (vim) |
+| `LANG` / `LC_ALL` | Locale (en_US.UTF-8) |
+| `FZF_DEFAULT_OPTS` | FZF appearance settings |
+| `FZF_DEFAULT_COMMAND` | FZF file finder command |