From f9913eeee78d765708830aec5941f72570fc3f73 Mon Sep 17 00:00:00 2001
From: "Aaron D. Lee" <aaron.daniel.lee@gmail.com>
Date: Sun, 14 Dec 2025 00:13:08 -0500
Subject: [PATCH] Added additional scripts and docs.

---
 LICENSE                |  21 ++
 README.md              | 373 ++++++++++++++++++++++++++++++++-
 bin/setup-espanso.sh   | 237 +++++++++++++++++++++
 bin/update-dotfiles.sh |   0
 docs/ESPANSO.md        | 454 +++++++++++++++++++++++++++++++++++++++++
 docs/SETUP_GUIDE.md    | 278 +++++++++++++++++++++++++
 install.sh             |   6 +-
 7 files changed, 1365 insertions(+), 4 deletions(-)
 create mode 100644 LICENSE
 create mode 100755 bin/setup-espanso.sh
 mode change 100644 => 100755 bin/update-dotfiles.sh
 create mode 100644 docs/ESPANSO.md
 create mode 100644 docs/SETUP_GUIDE.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..e6d835d
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+ MIT License
+ 
+ Copyright (c) 2025 Aaron D. Lee
+ 
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+ 
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+ 
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
diff --git a/README.md b/README.md
index 15742ee..a4f63eb 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,373 @@
-# dotfiles
+# ADLee's Dotfiles
+
+> Personal configuration files and automation scripts for a powerful, consistent development environment across Linux/macOS systems.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Shell](https://img.shields.io/badge/Shell-Zsh-green.svg)](https://www.zsh.org/)
+[![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/adlee-was-taken/dotfiles/graphs/commit-activity)
+
+## 📸 Preview
+
+```
+┌[alee@hostname]─[~/projects/dotfiles ⎇ main *]
+└%
+```
+
+## ✨ Features
+
+### 🎨 Custom Zsh Theme
+- **adlee.zsh-theme** - A feature-rich, performant zsh theme
+  - Git branch/status integration with visual indicators
+  - Command execution timer (shows time for commands > 10s)
+  - Smart path truncation for long directories
+  - User/root detection (blue prompt for users, red for root)
+  - Clean, minimal design that's easy to read
+
+### ⌨️ Espanso Text Expansion
+- **100+ pre-configured snippets** using `..trigger` syntax
+  - Date/time stamps (UTC, local, ISO 8601)
+  - Git shortcuts (`..gst`, `..gco`, `..gcm`)
+  - Docker commands (`..dps`, `..dcup`, `..dlog`)
+  - Code templates (bash, python, markdown)
+  - System info (`..ip`, `..user`, `..branch`)
+  - Common typo corrections
+  - Personal information templates
+
+### 🛠️ Modern CLI Tools
+- **fzf** - Fuzzy finder for files and history
+- **bat** - Syntax-highlighted file viewer
+- **eza** - Modern ls replacement with icons
+- **espanso** - Universal text expander
+
+### 🔄 Easy Deployment
+- **One-command installation** on new systems
+- **Automated backups** of existing configs
+- **System-wide theme deployment** for all users
+- **Modular architecture** for easy customization
+
+## 📁 Repository Structure
+
+```
+dotfiles/
+├── install.sh                      # Main installation script
+├── README.md                       # This file
+├── LICENSE                         # MIT License
+├── .gitignore                      # Git ignore rules
+│
+├── zsh/
+│   ├── .zshrc                      # Main zsh configuration
+│   └── themes/
+│       └── adlee.zsh-theme         # Custom zsh theme
+│
+├── espanso/
+│   ├── config/
+│   │   └── default.yml             # Espanso settings
+│   └── match/
+│       ├── base.yml                # Base snippets (100+ triggers)
+│       └── personal.yml            # Personal info snippets
+│
+├── git/
+│   ├── .gitconfig                  # Git configuration
+│   └── .gitignore_global           # Global gitignore patterns
+│
+├── vim/
+│   └── .vimrc                      # Vim configuration
+│
+├── tmux/
+│   └── .tmux.conf                  # Tmux configuration
+│
+├── bin/
+│   ├── update-dotfiles             # Update from repo
+│   ├── setup-espanso.sh            # Espanso setup wizard
+│   └── deploy-zshtheme-systemwide.sh  # System-wide deployment
+│
+└── docs/
+    ├── SETUP_GUIDE.md              # Detailed setup instructions
+    └── ESPANSO.md                  # Espanso reference guide
+```
+
+## 🚀 Quick Start
+
+### Option 1: One-Line Install (Recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash
+```
+
+### Option 2: Manual Install
+
+```bash
+# Clone the repository
+git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
+cd ~/.dotfiles
+
+# Run the installer
+./install.sh
+```
+
+### What Gets Installed?
+
+The installer will:
+1. ✅ Detect your OS (Ubuntu, Arch, Fedora, macOS)
+2. ✅ Install dependencies (git, curl, zsh)
+3. ✅ Backup existing configs to `~/.dotfiles_backup_YYYYMMDD_HHMMSS/`
+4. ✅ Install oh-my-zsh
+5. ✅ Create symlinks to dotfiles
+6. ✅ Optionally install espanso, fzf, bat, eza
+7. ✅ Set zsh as default shell
+
+## ⚙️ Post-Installation
+
+### Set Up Espanso
+
+Personalize your text expansion snippets:
+
+```bash
+cd ~/.dotfiles
+./bin/setup-espanso.sh
+```
+
+This wizard will:
+- Update `personal.yml` with your name, email, etc.
+- Install optional espanso packages (emoji, math symbols)
+- Show you useful triggers and tips
+
+### Test Espanso
+
+Try typing these anywhere:
+- `..date` → 2024-12-13
+- `..time` → 14:30:45
+- `..ip` → Your public IP
+- `..shrug` → ¯\\\_(ツ)_/¯
+
+Toggle espanso: `ALT+SHIFT+E`  
+Search snippets: `ALT+SPACE`
+
+### Deploy Theme System-Wide (Optional)
+
+To share the theme across all users on your system:
+
+```bash
+cd ~/.dotfiles
+sudo ./bin/deploy-zshtheme-systemwide.sh --all
+```
+
+Options:
+- `--all` - Deploy to all users with oh-my-zsh
+- `--current` - Deploy to current user + root only
+- `--status` - Show deployment status
+- `--force` - Force replace existing links
+
+## 🔄 Updating
+
+### Update Dotfiles from GitHub
+
+```bash
+cd ~/.dotfiles
+git pull origin main
+./install.sh  # Re-link updated files
+```
+
+Or use the helper script:
+
+```bash
+update-dotfiles
+```
+
+### Push Changes to GitHub
+
+```bash
+cd ~/.dotfiles
+git add .
+git commit -m "Update theme colors"
+git push origin main
+```
+
+## 🎨 Customization
+
+### Modify the Zsh Theme
+
+```bash
+vim ~/.dotfiles/zsh/themes/adlee.zsh-theme
+source ~/.zshrc  # Test changes
+```
+
+### Add Custom Aliases
+
+Edit `~/.dotfiles/zsh/.zshrc` and add to the aliases section:
+
+```bash
+# Custom aliases
+alias projects='cd ~/projects'
+alias dc='docker-compose'
+```
+
+### Add Espanso Snippets
+
+Edit `~/.dotfiles/espanso/match/base.yml`:
+
+```yaml
+matches:
+  - trigger: "..myproject"
+    replace: "cd ~/projects/my-awesome-project"
+```
+
+Then restart espanso:
+```bash
+espanso restart
+```
+
+## 📚 Documentation
+
+- **[SETUP_GUIDE.md](docs/SETUP_GUIDE.md)** - Detailed setup instructions
+- **[ESPANSO.md](docs/ESPANSO.md)** - Complete espanso reference
+- **[Zsh Theme Variables](zsh/themes/adlee.zsh-theme)** - Customize colors and format
+
+## 🌟 Espanso Quick Reference
+
+### Date & Time
+| Trigger | Output |
+|---------|--------|
+| `..date` | 2024-12-13 |
+| `..time` | 14:30:45 |
+| `..ts` | 2024-12-13T14:30:45.123Z |
+| `..epoch` | 1702476645 |
+
+### Git Shortcuts
+| Trigger | Output |
+|---------|--------|
+| `..gst` | `git status` |
+| `..gco` | `git checkout ` |
+| `..gcm` | `git commit -m ""` |
+| `..branch` | Current git branch name |
+
+### System Info
+| Trigger | Output |
+|---------|--------|
+| `..user` | Current username |
+| `..host` | Hostname |
+| `..ip` | Public IP address |
+| `..pwd` | Current directory |
+
+### Emoticons
+| Trigger | Output |
+|---------|--------|
+| `..shrug` | ¯\\\_(ツ)_/¯ |
+| `..flip` | (╯°□°)╯︵ ┻━┻ |
+| `..check` | ✓ |
+
+[See full list in ESPANSO.md](docs/ESPANSO.md)
+
+## 🖥️ Multi-System Setup
+
+### Deploy to New System
+
+```bash
+# On the new system
+git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
+cd ~/.dotfiles
+./install.sh
+```
+
+### Sync Changes Between Systems
+
+```bash
+# On system A (make changes)
+cd ~/.dotfiles
+git add .
+git commit -m "Update aliases"
+git push
+
+# On system B (pull changes)
+cd ~/.dotfiles
+git pull
+source ~/.zshrc
+```
+
+## 🔧 Troubleshooting
+
+### Theme Not Loading
+
+Ensure `ZSH_THEME="adlee"` in `~/.zshrc`:
+```bash
+grep ZSH_THEME ~/.zshrc
+```
+
+Then reload:
+```bash
+source ~/.zshrc
+```
+
+### Espanso Not Expanding
+
+Check if espanso is running:
+```bash
+espanso status
+```
+
+If not running:
+```bash
+espanso service start
+```
+
+View logs:
+```bash
+espanso log
+```
+
+### Symlinks Broken
+
+Remove broken symlinks:
+```bash
+find ~ -maxdepth 1 -type l -xtype l -delete
+```
+
+Re-run installation:
+```bash
+cd ~/.dotfiles && ./install.sh
+```
+
+### Permission Errors
+
+Make scripts executable:
+```bash
+chmod +x ~/.dotfiles/install.sh
+chmod +x ~/.dotfiles/bin/*
+```
+
+## 🤝 Contributing
+
+This is a personal dotfiles repository, but suggestions and improvements are welcome!
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/improvement`)
+3. Commit your changes (`git commit -m 'Add some improvement'`)
+4. Push to the branch (`git push origin feature/improvement`)
+5. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [oh-my-zsh](https://ohmyz.sh/) - Zsh configuration framework
+- [espanso](https://espanso.org/) - Text expander
+- [fzf](https://github.com/junegunn/fzf) - Fuzzy finder
+- [bat](https://github.com/sharkdp/bat) - Cat clone with syntax highlighting
+- [eza](https://github.com/eza-community/eza) - Modern ls replacement
+
+## 🔗 Resources
+
+- [Arch Linux Wiki: Dotfiles](https://wiki.archlinux.org/title/Dotfiles)
+- [GitHub: Awesome Dotfiles](https://github.com/webpro/awesome-dotfiles)
+- [Espanso Hub](https://hub.espanso.org/)
+
+---
+
+**Author**: Aaron D. Lee  
+**Repository**: https://github.com/adlee-was-taken/dotfiles  
+**Last Updated**: 2024-12-13
+
+⭐ If you find this useful, consider giving it a star!# dotfiles
 Aaron D. Lee's dotfiles for Linux/MacOs
diff --git a/bin/setup-espanso.sh b/bin/setup-espanso.sh
new file mode 100755
index 0000000..a546691
--- /dev/null
+++ b/bin/setup-espanso.sh
@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+# ============================================================================
+# Espanso Setup and Configuration Script
+# ============================================================================
+# This script helps set up espanso with custom configurations
+
+set -e
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+print_header() {
+    echo -e "\n${BLUE}╔════════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${BLUE}║${NC}  Espanso Setup Script                                     ${BLUE}║${NC}"
+    echo -e "${BLUE}╚════════════════════════════════════════════════════════════╝${NC}\n"
+}
+
+print_step() {
+    echo -e "${GREEN}==>${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}✓${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}⚠${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}✗${NC} $1"
+}
+
+ask_yes_no() {
+    local prompt="$1"
+    local default="${2:-y}"
+
+    if [[ "$default" == "y" ]]; then
+        prompt="$prompt [Y/n]: "
+    else
+        prompt="$prompt [y/N]: "
+    fi
+
+    read -p "$prompt" response
+    response=${response:-$default}
+
+    [[ "$response" =~ ^[Yy]$ ]]
+}
+
+check_espanso() {
+    if ! command -v espanso &> /dev/null; then
+        print_error "espanso is not installed"
+        echo "Install it from: https://espanso.org/install/"
+        echo "Or run the main dotfiles install script"
+        exit 1
+    fi
+    print_success "espanso is installed: $(espanso --version)"
+}
+
+show_espanso_status() {
+    print_step "Checking espanso status"
+
+    if espanso status | grep -q "running"; then
+        print_success "espanso service is running"
+    else
+        print_warning "espanso service is not running"
+        if ask_yes_no "Start espanso service?"; then
+            espanso service start
+            print_success "espanso service started"
+        fi
+    fi
+}
+
+personalize_config() {
+    print_step "Personalizing espanso configuration"
+
+    local personal_file="$HOME/.config/espanso/match/personal.yml"
+
+    if [ ! -f "$personal_file" ]; then
+        print_error "Personal config file not found: $personal_file"
+        return 1
+    fi
+
+    echo
+    echo "Let's personalize your espanso configuration!"
+    echo
+
+    read -p "Your full name: " fullname
+    read -p "Your email: " email
+    read -p "Your phone (optional): " phone
+    read -p "Your website (optional): " website
+    read -p "Your GitHub username (optional): " github
+
+    # Create a backup
+    cp "$personal_file" "$personal_file.backup"
+
+    # Update the personal.yml file
+    sed -i "s/your.email@example.com/$email/g" "$personal_file"
+    sed -i "s/Your Full Name/$fullname/g" "$personal_file"
+
+    if [ -n "$phone" ]; then
+        sed -i "s/+1 (555) 123-4567/$phone/g" "$personal_file"
+    fi
+
+    if [ -n "$website" ]; then
+        sed -i "s|https://yourwebsite.com|$website|g" "$personal_file"
+    fi
+
+    if [ -n "$github" ]; then
+        sed -i "s/yourusername/$github/g" "$personal_file"
+    fi
+
+    print_success "Personal configuration updated!"
+    print_warning "Backup saved to: $personal_file.backup"
+}
+
+install_packages() {
+    print_step "Installing espanso packages"
+
+    echo
+    echo "Available packages to install:"
+    echo "  1. emoji - Emoji snippets (e.g., :smile: → 😊)"
+    echo "  2. greek-letters - Greek letters (e.g., :alpha: → α)"
+    echo "  3. math - Math symbols (e.g., :sum: → ∑)"
+    echo "  4. accents - Accented characters"
+    echo "  5. all-emojis - Complete emoji collection"
+    echo
+
+    if ask_yes_no "Install emoji package?"; then
+        espanso install emoji --force
+        print_success "Emoji package installed"
+    fi
+
+    if ask_yes_no "Install greek-letters package?"; then
+        espanso install greek-letters --force
+        print_success "Greek letters package installed"
+    fi
+
+    if ask_yes_no "Install math package?"; then
+        espanso install math --force
+        print_success "Math package installed"
+    fi
+}
+
+list_installed_packages() {
+    print_step "Installed espanso packages"
+    echo
+    espanso package list
+    echo
+}
+
+show_usage_tips() {
+    print_step "Usage tips"
+
+    cat << EOF
+
+${GREEN}Espanso Quick Start:${NC}
+
+${YELLOW}Toggle espanso on/off:${NC}
+  ALT+SHIFT+E
+
+${YELLOW}Open search menu:${NC}
+  ALT+SPACE
+
+${YELLOW}Basic triggers (from base.yml):${NC}
+  :date       → Current date (YYYY-MM-DD)
+  :time       → Current time (HH:MM:SS)
+  :datetime   → Full datetime
+  :shrug      → ¯\\_(ツ)_/¯
+  :flip       → (╯°□°)╯︵ ┻━┻
+
+${YELLOW}Code snippets:${NC}
+  :bash       → Bash script template
+  :python     → Python script template
+  :mdcode     → Markdown code block
+
+${YELLOW}Git shortcuts:${NC}
+  :gst        → git status
+  :gco        → git checkout
+  :gcm        → git commit -m ""
+
+${YELLOW}Personal (customize in personal.yml):${NC}
+  :myemail    → Your email
+  :myname     → Your name
+  :sig        → Email signature
+
+${YELLOW}Espanso commands:${NC}
+  espanso status              - Check if running
+  espanso restart             - Restart service
+  espanso edit                - Edit config
+  espanso log                 - View logs
+  espanso package list        - List installed packages
+  espanso package install X   - Install package
+
+${YELLOW}Configuration files:${NC}
+  ~/.config/espanso/config/default.yml   - Main config
+  ~/.config/espanso/match/base.yml       - Base snippets
+  ~/.config/espanso/match/personal.yml   - Personal snippets
+
+${GREEN}Create your own snippets!${NC}
+Edit the YAML files above to add custom triggers.
+
+EOF
+}
+
+main() {
+    print_header
+
+    check_espanso
+    show_espanso_status
+
+    echo
+    if ask_yes_no "Personalize your configuration?"; then
+        personalize_config
+    fi
+
+    echo
+    if ask_yes_no "Install additional espanso packages?"; then
+        install_packages
+    fi
+
+    echo
+    list_installed_packages
+
+    echo
+    show_usage_tips
+
+    echo
+    print_success "Espanso setup complete!"
+    echo
+    echo "Try typing ${YELLOW}:date${NC} in any application to test it!"
+}
+
+main "$@"
diff --git a/bin/update-dotfiles.sh b/bin/update-dotfiles.sh
old mode 100644
new mode 100755
diff --git a/docs/ESPANSO.md b/docs/ESPANSO.md
new file mode 100644
index 0000000..ec6053f
--- /dev/null
+++ b/docs/ESPANSO.md
@@ -0,0 +1,454 @@
+# Espanso Quick Reference Guide
+
+A comprehensive guide to using espanso text expansion in your dotfiles setup.
+
+## 🚀 Getting Started
+
+### Installation
+
+Espanso is automatically installed when you run the main install script:
+
+```bash
+./install.sh
+```
+
+Or install it separately:
+
+```bash
+# Ubuntu/Debian
+wget https://github.com/espanso/espanso/releases/latest/download/espanso-debian-x11-amd64.deb
+sudo apt install ./espanso-debian-x11-amd64.deb
+espanso service register
+
+# macOS
+brew tap espanso/espanso
+brew install espanso
+espanso service register
+
+# Fedora
+# See: https://espanso.org/install/
+```
+
+### Initial Setup
+
+Run the setup wizard to personalize your configuration:
+
+```bash
+./bin/setup-espanso.sh
+```
+
+This will:
+- Personalize your snippets with your information
+- Install optional espanso packages
+- Show you useful triggers and tips
+
+## ⌨️ Basic Controls
+
+| Action | Shortcut |
+|--------|----------|
+| Toggle espanso on/off | `ALT+SHIFT+E` |
+| Open search menu | `ALT+SPACE` |
+| Restart espanso | `espanso restart` |
+| Check status | `espanso status` |
+
+## 📝 Built-in Snippets
+
+### Date & Time
+
+| Trigger | Output | Example |
+|---------|--------|---------|
+| `:date` | Current date | 2024-12-13 |
+| `:time` | Current time | 14:30:45 |
+| `:datetime` | Date and time | 2024-12-13 14:30:45 |
+| `:now` | Formatted datetime | December 13, 2024 at 02:30 PM |
+
+### Emoticons & Symbols
+
+| Trigger | Output |
+|---------|--------|
+| `:shrug` | ¯\\\_(ツ)_/¯ |
+| `:flip` | (╯°□°)╯︵ ┻━┻ |
+| `:unflip` | ┬─┬ ノ( ゜-゜ノ) |
+| `:lenny` | ( ͡° ͜ʖ ͡°) |
+| `:arrow` | → |
+| `:larrow` | ← |
+| `:check` | ✓ |
+| `:cross` | ✗ |
+| `:star` | ★ |
+| `:heart` | ♥ |
+
+### Code Templates
+
+| Trigger | Output |
+|---------|--------|
+| `:bash` | Bash script template with shebang |
+| `:python` | Python script template |
+| `:shebang` | `#!/usr/bin/env bash` |
+| `:gitignore` | Complete .gitignore template |
+| `:mdcode` | Markdown code block |
+| `:mdtable` | Markdown table template |
+
+### Git Shortcuts
+
+| Trigger | Output |
+|---------|--------|
+| `:gst` | `git status` |
+| `:gco` | `git checkout ` |
+| `:gcm` | `git commit -m ""` |
+| `:glog` | `git log --oneline --graph --decorate --all` |
+
+### Docker Shortcuts
+
+| Trigger | Output |
+|---------|--------|
+| `:dps` | `docker ps` |
+| `:dcup` | `docker-compose up -d` |
+| `:dcdown` | `docker-compose down` |
+
+### Personal Information (Customizable)
+
+| Trigger | Output |
+|---------|--------|
+| `:myemail` | Your email address |
+| `:myname` | Your full name |
+| `:myphone` | Your phone number |
+| `:mywebsite` | Your website URL |
+| `:mygithub` | Your GitHub profile |
+| `:sig` | Your email signature |
+
+### Text Templates
+
+| Trigger | Output |
+|---------|--------|
+| `:lorem` | Lorem ipsum paragraph |
+| `:loremlong` | Extended lorem ipsum |
+| `:emailhi` | Email greeting template |
+| `:emailthanks` | Thank you email template |
+| `:mdheader` | Markdown document header |
+| `:meeting` | Meeting notes template |
+
+## 🎨 Creating Custom Snippets
+
+Edit your snippet files:
+
+```bash
+# Base snippets (general use)
+vim ~/.config/espanso/match/base.yml
+
+# Personal snippets (your info)
+vim ~/.config/espanso/match/personal.yml
+```
+
+### Simple Text Replacement
+
+```yaml
+matches:
+  - trigger: ":hw"
+    replace: "Hello, World!"
+```
+
+### With Variables (Dynamic Content)
+
+```yaml
+matches:
+  - trigger: ":mydate"
+    replace: "Today is {{mydate}}"
+    vars:
+      - name: mydate
+        type: date
+        params:
+          format: "%B %d, %Y"
+```
+
+### Multi-line Templates
+
+```yaml
+matches:
+  - trigger: ":email"
+    replace: |
+      Dear {{name}},
+      
+      
+      
+      Best regards,
+      Your Name
+    vars:
+      - name: name
+        type: form
+        params:
+          layout: "Recipient name: {{name}}"
+```
+
+### With Shell Commands
+
+```yaml
+matches:
+  - trigger: ":myip"
+    replace: "{{output}}"
+    vars:
+      - name: output
+        type: shell
+        params:
+          cmd: "curl -s ifconfig.me"
+```
+
+### Cursor Positioning
+
+```yaml
+matches:
+  - trigger: ":func"
+    replace: "function {{name}}() {\n    {{cursor}}\n}"
+    vars:
+      - name: name
+        type: form
+        params:
+          layout: "Function name: {{name}}"
+```
+
+## 📦 Package Management
+
+### List Installed Packages
+
+```bash
+espanso package list
+```
+
+### Install Packages
+
+```bash
+# Emoji support
+espanso install emoji --force
+
+# Greek letters
+espanso install greek-letters --force
+
+# Math symbols
+espanso install math --force
+
+# All emojis
+espanso install all-emojis --force
+```
+
+### Browse Available Packages
+
+Visit: https://hub.espanso.org/
+
+## 🔧 Configuration
+
+### Main Configuration File
+
+Location: `~/.config/espanso/config/default.yml`
+
+Key settings:
+
+```yaml
+# Toggle key
+toggle_key: ALT+SHIFT+E
+
+# Search shortcut
+search_shortcut: ALT+SPACE
+
+# Backend (Auto, Clipboard, or Inject)
+backend: Auto
+
+# Show notifications
+show_notifications: true
+
+# Auto-restart on config changes
+auto_restart: true
+```
+
+### Application-Specific Configs
+
+Create configs for specific applications:
+
+```bash
+# Only in terminal
+vim ~/.config/espanso/match/terminal.yml
+```
+
+```yaml
+filter_title: "Terminal|Konsole|iTerm"
+
+matches:
+  - trigger: ":ll"
+    replace: "ls -lah"
+```
+
+## 🛠️ Troubleshooting
+
+### Espanso Not Working
+
+1. Check if running:
+   ```bash
+   espanso status
+   ```
+
+2. Restart the service:
+   ```bash
+   espanso restart
+   ```
+
+3. Check logs:
+   ```bash
+   espanso log
+   ```
+
+### Snippets Not Expanding
+
+1. Verify the trigger syntax in your YAML files
+2. Check for YAML syntax errors:
+   ```bash
+   espanso match list
+   ```
+3. Ensure espanso is enabled (not toggled off with ALT+SHIFT+E)
+
+### Conflicts with Other Apps
+
+Some applications may conflict with espanso. Add them to the filter:
+
+```yaml
+# In config/default.yml
+filter_exec: "application_name"
+```
+
+### Clipboard Issues
+
+Try changing the backend:
+
+```yaml
+# In config/default.yml
+backend: Clipboard
+```
+
+## 📚 Advanced Features
+
+### Forms (Interactive Inputs)
+
+```yaml
+matches:
+  - trigger: ":invoice"
+    replace: |
+      Invoice #{{number}}
+      Client: {{client}}
+      Amount: ${{amount}}
+      Due: {{date}}
+    vars:
+      - name: number
+        type: form
+        params:
+          layout: |
+            Invoice Number: {{number}}
+            Client Name: {{client}}
+            Amount: {{amount}}
+            Due Date: {{date}}
+```
+
+### Choice Variables
+
+```yaml
+matches:
+  - trigger: ":env"
+    replace: "{{env}}"
+    vars:
+      - name: env
+        type: choice
+        params:
+          values:
+            - development
+            - staging
+            - production
+```
+
+### Script Variables
+
+```yaml
+matches:
+  - trigger: ":weather"
+    replace: "{{output}}"
+    vars:
+      - name: output
+        type: script
+        params:
+          args:
+            - python
+            - /path/to/weather_script.py
+```
+
+## 🔄 Backup and Sync
+
+### Backup Your Config
+
+```bash
+# Using the dotfiles system
+cd ~/.dotfiles
+git add espanso/
+git commit -m "Update espanso config"
+git push
+```
+
+### Restore on New System
+
+```bash
+# Clone dotfiles
+git clone https://github.com/YOUR_USERNAME/dotfiles.git ~/.dotfiles
+cd ~/.dotfiles
+
+# Install
+./install.sh
+
+# Personalize
+./bin/setup-espanso.sh
+```
+
+## 📖 Resources
+
+- [Official Documentation](https://espanso.org/docs/)
+- [Package Hub](https://hub.espanso.org/)
+- [GitHub Repository](https://github.com/espanso/espanso)
+- [Community Forum](https://github.com/espanso/espanso/discussions)
+
+## 💡 Tips & Best Practices
+
+1. **Use consistent prefixes**: Start all triggers with `:` to avoid accidents
+2. **Keep it organized**: Separate snippets by category in different files
+3. **Test before committing**: Verify new snippets work before adding to git
+4. **Use descriptive triggers**: Make triggers memorable and logical
+5. **Leverage forms**: Use forms for snippets that need customization
+6. **Back up regularly**: Keep your config in version control
+7. **Share useful snippets**: Contribute to the community hub
+
+## 🎯 Common Use Cases
+
+### Developer Workflow
+
+```yaml
+:fixme    → // FIXME: 
+:todo     → // TODO: 
+:note     → // NOTE: 
+:debug    → console.log('DEBUG:', );
+```
+
+### Writing & Documentation
+
+```yaml
+:doc      → Documentation template
+:readme   → README.md template
+:license  → MIT License text
+:quote    → > Blockquote
+```
+
+### Communication
+
+```yaml
+:ty       → Thank you
+:yw       → You're welcome
+:lgtm     → Looks good to me
+:wip      → Work in progress
+```
+
+---
+
+**Happy expanding!** 🚀
+
+For questions or issues, check the [espanso documentation](https://espanso.org/docs/) or open an issue in your dotfiles repository.
diff --git a/docs/SETUP_GUIDE.md b/docs/SETUP_GUIDE.md
new file mode 100644
index 0000000..5504f43
--- /dev/null
+++ b/docs/SETUP_GUIDE.md
@@ -0,0 +1,278 @@
+# Dotfiles Repository Setup Checklist
+
+Use this checklist to ensure your dotfiles repository is complete and ready to use.
+
+## 📋 File Structure
+
+### Core Files
+- [ ] `README.md` - Main documentation (use the artifact provided)
+- [ ] `LICENSE` - MIT License file
+- [ ] `.gitignore` - Git ignore rules
+- [ ] `install.sh` - Main installation script
+
+### Zsh Configuration
+- [ ] `zsh/.zshrc` - Main zsh config
+- [ ] `zsh/themes/adlee.zsh-theme` - Custom theme
+- [ ] `zsh/.zshrc.local.example` - Template for local settings (optional)
+
+### Espanso Configuration
+- [ ] `espanso/config/default.yml` - Espanso settings
+- [ ] `espanso/match/base.yml` - Base snippets
+- [ ] `espanso/match/personal.yml` - Personal snippets
+
+### Git Configuration
+- [ ] `git/.gitconfig` - Git settings
+- [ ] `git/.gitignore_global` - Global gitignore (optional)
+
+### Other Configs
+- [ ] `vim/.vimrc` - Vim config (if you use vim)
+- [ ] `tmux/.tmux.conf` - Tmux config (if you use tmux)
+
+### Utility Scripts
+- [ ] `bin/update-dotfiles` - Update script
+- [ ] `bin/setup-espanso.sh` - Espanso wizard
+- [ ] `bin/deploy-zshtheme-systemwide.sh` - System-wide deployment
+
+### Documentation
+- [ ] `docs/SETUP_GUIDE.md` - Detailed setup guide
+- [ ] `docs/ESPANSO.md` - Espanso reference
+- [ ] `CHECKLIST.md` - This file
+
+## 🔧 Setup Steps
+
+### 1. Create Directory Structure
+```bash
+cd ~/.dotfiles
+mkdir -p zsh/themes
+mkdir -p espanso/config espanso/match
+mkdir -p git
+mkdir -p vim
+mkdir -p tmux
+mkdir -p bin
+mkdir -p docs
+```
+
+### 2. Create/Copy Configuration Files
+
+- [ ] Copy your existing `.zshrc` to `zsh/.zshrc`
+- [ ] Copy your theme to `zsh/themes/adlee.zsh-theme`
+- [ ] Copy espanso configs from `~/.config/espanso/` to `espanso/`
+- [ ] Copy `.gitconfig` to `git/.gitconfig`
+- [ ] Copy `.vimrc` to `vim/.vimrc` (if exists)
+- [ ] Copy `.tmux.conf` to `tmux/.tmux.conf` (if exists)
+
+### 3. Create Scripts
+
+Download or create these scripts from the artifacts:
+- [ ] `install.sh`
+- [ ] `bin/update-dotfiles`
+- [ ] `bin/setup-espanso.sh`
+- [ ] `bin/deploy-zshtheme-systemwide.sh`
+
+Make them executable:
+```bash
+chmod +x install.sh
+chmod +x bin/*
+```
+
+### 4. Create Documentation
+
+- [ ] Create `README.md` (use artifact provided)
+- [ ] Create `docs/SETUP_GUIDE.md` (artifact provided earlier)
+- [ ] Create `docs/ESPANSO.md` (artifact provided earlier)
+
+### 5. Create .gitignore
+
+```bash
+cat > .gitignore << 'EOF'
+# OS files
+.DS_Store
+Thumbs.db
+
+# Backup files
+*.backup
+*.bak
+*~
+
+# Local machine-specific configs
+*.local
+.zshrc.local
+
+# Sensitive information
+.env
+.env.*
+secrets/
+
+# Optional: Uncomment if personal espanso info is sensitive
+# espanso/match/personal.yml
+
+# Espanso backup files
+espanso/match/*.backup
+EOF
+```
+
+### 6. Create LICENSE
+
+```bash
+cat > LICENSE << 'EOF'
+MIT License
+
+Copyright (c) 2024 Aaron D. Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+EOF
+```
+
+## 🐙 GitHub Setup
+
+### 1. Create Repository
+- [ ] Go to https://github.com/new
+- [ ] Name: `dotfiles`
+- [ ] Description: "Personal configuration files and automation scripts"
+- [ ] Visibility: Public or Private
+- [ ] Don't initialize with README (you already have one)
+- [ ] Click "Create repository"
+
+### 2. Initialize Git
+```bash
+cd ~/.dotfiles
+git init
+git add .
+git commit -m "Initial commit: Add dotfiles and custom zsh theme"
+```
+
+### 3. Add Remote and Push
+```bash
+# Replace adlee-was-taken with your GitHub username
+git remote add origin https://github.com/adlee-was-taken/dotfiles.git
+git branch -M main
+git push -u origin main
+```
+
+### 4. Update URLs in Files
+- [ ] Update `install.sh` - Replace `adlee-was-taken` in `DOTFILES_REPO`
+- [ ] Update `README.md` - Replace all `adlee-was-taken` references
+- [ ] Update `docs/SETUP_GUIDE.md` - Replace `adlee-was-taken`
+
+```bash
+# Quick find all instances
+grep -r "adlee-was-taken" .
+```
+
+## ✅ Verification
+
+### Test Local Installation
+- [ ] Test install script on local machine
+  ```bash
+  # Dry run first
+  bash -n install.sh  # Check for syntax errors
+  
+  # Then test (will backup existing configs)
+  ./install.sh
+  ```
+
+- [ ] Verify symlinks were created correctly
+  ```bash
+  ls -la ~ | grep "^l"  # Show all symlinks in home
+  ```
+
+- [ ] Test zsh theme
+  ```bash
+  source ~/.zshrc
+  # Check if prompt looks correct
+  ```
+
+- [ ] Test espanso
+  ```bash
+  espanso status
+  # Try typing: ..date
+  ```
+
+### Test GitHub Setup
+- [ ] Clone on a test directory
+  ```bash
+  cd /tmp
+  git clone https://github.com/adlee-was-taken/dotfiles.git test-dotfiles
+  cd test-dotfiles
+  ./install.sh
+  ```
+
+### Test System-wide Deployment
+- [ ] Check current status
+  ```bash
+  sudo ./bin/deploy-zshtheme-systemwide.sh --status
+  ```
+
+- [ ] Test deployment
+  ```bash
+  sudo ./bin/deploy-zshtheme-systemwide.sh --current
+  ```
+
+## 📝 Final Touches
+
+### Customize Personal Info
+- [ ] Edit `espanso/match/personal.yml` with your info
+- [ ] Edit `git/.gitconfig` with your name and email
+- [ ] Update `README.md` with your GitHub username
+- [ ] Update any other personal references
+
+### Optional Enhancements
+- [ ] Add GitHub Actions for linting (optional)
+- [ ] Add screenshots to README
+- [ ] Create a demo GIF of the theme
+- [ ] Add more espanso snippets for your workflow
+- [ ] Create shell aliases in `.zshrc`
+
+### Security Check
+- [ ] Ensure no sensitive info in committed files
+  ```bash
+  # Search for potential secrets
+  grep -rE '(password|secret|token|key)' . --exclude-dir=.git
+  ```
+
+- [ ] Verify `.gitignore` is working
+  ```bash
+  git status  # Should not show .local files or sensitive data
+  ```
+
+## 🎉 You're Done!
+
+Once all items are checked:
+- [ ] Commit any final changes
+  ```bash
+  git add .
+  git commit -m "Complete repository setup"
+  git push
+  ```
+
+- [ ] Test on a second machine (if available)
+- [ ] Star your own repo (you deserve it! 😄)
+- [ ] Share with others who might find it useful
+
+## 📚 Next Steps
+
+- Read through `docs/SETUP_GUIDE.md` for detailed usage
+- Explore `docs/ESPANSO.md` for all available snippets
+- Customize the theme colors in `zsh/themes/adlee.zsh-theme`
+- Add more aliases to `.zshrc`
+- Consider contributing to the espanso community hub
+
+---
+
+**Need help?** Open an issue in your repository or check the documentation files.
diff --git a/install.sh b/install.sh
index 74480fc..b615c54 100755
--- a/install.sh
+++ b/install.sh
@@ -2,8 +2,8 @@
 # ============================================================================
 # ADLee's Dotfiles Installation Script
 # ============================================================================
-# Quick install: curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/dotfiles/main/install.sh | bash
-# Or: git clone https://github.com/YOUR_USERNAME/dotfiles.git && cd dotfiles && ./install.sh
+# Quick install: curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash
+# Or: git clone https://github.com/adlee-was-taken/dotfiles.git && cd dotfiles && ./install.sh
 
 set -e
 
@@ -11,7 +11,7 @@ set -e
 # Configuration
 # ============================================================================
 
-DOTFILES_REPO="https://github.com/YOUR_USERNAME/dotfiles.git"
+DOTFILES_REPO="https://github.com/adlee-was-taken/dotfiles.git"
 DOTFILES_DIR="$HOME/.dotfiles"
 BACKUP_DIR="$HOME/.dotfiles_backup_$(date +%Y%m%d_%H%M%S)"