dotfiles/USAGE.md

Dotfiles Usage Guide

Quick Start

Initial Deployment

# Deploy complete system
~/dotfiles/engage

# Or deploy specific components
~/dotfiles/engage packages  # Install Homebrew packages
~/dotfiles/engage config    # Deploy configuration files  
~/dotfiles/engage system    # Set macOS defaults

Daily Operations

# System maintenance
sysupdate              # Safe system update with rollback protection
deep_clean             # Comprehensive cleanup (brew, cache, logs)

# Health monitoring  
~/dotfiles/scripts/system-health.sh        # Dashboard view
~/dotfiles/scripts/system-health.sh monitor # Continuous monitoring

# Configuration drift detection
~/dotfiles/scripts/detect-drift.sh         # Full drift report
~/dotfiles/scripts/detect-drift.sh --quiet # Silent check (for automation)

Core Commands

System Maintenance Functions

sysupdate()

Enhanced system update with safety features:

sysupdate              # Interactive update with prompts
sysupdate --force      # Skip confirmation prompts
sysupdate --backup     # Create snapshot before updating

Features:

• Creates system snapshot before updates
• Verifies critical tools after updates
• Updates lockfile automatically
• Provides rollback on failure

deep_clean()

Comprehensive system cleanup:

deep_clean             # Interactive cleanup
deep_clean --aggressive # More thorough cleanup

What it cleans:

• Homebrew cache and old versions
• System caches and logs
• Development tool caches (npm, pip, etc.)
• Temporary files and downloads

Context-Aware Functions

Vault Integration (Obsidian)

today                  # Open today's note in Obsidian
weekly                 # Open weekly planning note
vf "search term"       # Find files in vault
vault                  # Navigate to vault directory

Git Enhancements

gst                    # Enhanced git status with context
gco                    # Smart git checkout with branch suggestions
gp                     # Push with upstream tracking

Development Tools

Quick Navigation

z pattern              # Zoxide smart directory jumping
..                     # Go up one directory
...                    # Go up two directories  
....                   # Go up three directories

File Operations

ll                     # Detailed file listing with colors
la                     # List all files including hidden
lt                     # Tree view of directories

Scripts Directory

Core Scripts

generate-lockfile.sh

Creates version snapshots for reproducible installations:

~/dotfiles/scripts/generate-lockfile.sh

• Captures current package versions
• Shows differences from previous lock
• Essential for system reproducibility

safe-update.sh

System update with rollback protection:

~/dotfiles/scripts/safe-update.sh

• Creates pre-update snapshot
• Tests system health after updates
• Automatic rollback on failure
• Keeps audit trail of changes

detect-drift.sh

Configuration consistency monitoring:

# Full drift analysis
~/dotfiles/scripts/detect-drift.sh

# Quiet mode (for automation)  
~/dotfiles/scripts/detect-drift.sh --quiet

# View last report
~/dotfiles/scripts/detect-drift.sh --report

Drift types detected:

• Package drift (installed vs. Brewfile)
• Configuration drift (live vs. repository)
• System settings drift (current vs. defaults)

system-health.sh

System monitoring and observability:

# Dashboard view (default)
~/dotfiles/scripts/system-health.sh

# Continuous monitoring
~/dotfiles/scripts/system-health.sh monitor

# JSON output for automation
~/dotfiles/scripts/system-health.sh json

Monitored components:

• System resources (CPU, memory, disk)
• Critical services health
• Package status
• Network connectivity
• Security posture

backup-ssh-keys.sh

Secure backup of SSH keys:

~/dotfiles/scripts/backup-ssh-keys.sh

• GPG encryption of private keys
• Generates restore instructions
• Manages backup retention

Shell Configuration

Environment Variables

Key environment variables set by the system:

EDITOR=nvim                    # Default editor
PAGER=less                     # Default pager  
BROWSER=open                   # Default browser (macOS)
CURRENT_CONTEXT=detected       # Current working context
HOMEBREW_NO_ANALYTICS=1        # Privacy setting

PATH Management

The system intelligently builds PATH from multiple sources:

• Homebrew binaries (/opt/homebrew/bin)
• User binaries (~/.local/bin)
• System binaries (/usr/local/bin, /usr/bin)
• Context-specific paths

PATH deduplication ensures no duplicates and optimal ordering.

Plugin Management

Plugins managed via Antidote from shell/.zsh-plugins.txt:

# Core plugins
ohmyzsh/ohmyzsh path:plugins/git
zsh-users/zsh-syntax-highlighting
zsh-users/zsh-autosuggestions
romkatv/powerlevel10k kind:fpath

Context-Aware Behavior

Work Context

Triggered when: PWD contains "work"
Features:

• Enhanced security prompts
• Work-specific aliases
• Stricter file permissions

Chamber Context

Triggered when: PWD contains "chamber" Features:

• Creative workspace optimizations
• Media tool shortcuts
• Relaxed security for experimentation

Vault Context

Triggered when: PWD contains "vault"
Features:

• Obsidian integration shortcuts
• Knowledge management tools
• Quick note creation

Dotfiles Context

Triggered when: PWD contains "dotfiles" Features:

• System administration tools
• Enhanced git shortcuts
• Configuration testing utilities

Automation and Monitoring

Automated Health Checks

Set up automated monitoring with cron or launchd:

# Check drift daily (example crontab entry)
0 9 * * * ~/dotfiles/scripts/detect-drift.sh --quiet || echo "Drift detected"

# Weekly health reports
0 9 * * 1 ~/dotfiles/scripts/system-health.sh json > ~/health-$(date +\%Y\%m\%d).json

Integration with CI/CD

Scripts return appropriate exit codes for automation:

• 0: Success/healthy
• 1: Warning/degraded
• 2: Error/unhealthy

Troubleshooting

Common Issues

Shell Not Loading Properly

# Check for syntax errors
zsh -n ~/.zshrc

# Load with debugging
zsh -x ~/.zshrc

Missing Tools

# Install missing Homebrew packages
brew bundle --file=~/dotfiles/Brewfile

# Check for available updates
brew outdated

Performance Issues

# Check shell load time
time (zsh -i -c exit)

# Monitor system health
~/dotfiles/scripts/system-health.sh monitor

Configuration Drift

# Detect and fix drift
~/dotfiles/scripts/detect-drift.sh

# Re-sync configurations
~/dotfiles/engage config

Recovery Procedures

System Rollback

If updates break the system:

# View available snapshots
ls ~/.system-snapshots/

# Manual rollback (guided by snapshot contents)
cat ~/.system-snapshots/TIMESTAMP/restore-instructions.txt

Configuration Reset

# Backup current config
cp ~/.zshrc ~/.zshrc.backup

# Restore from dotfiles
ln -sf ~/dotfiles/shell/.zshrc ~/.zshrc

Best Practices

Regular Maintenance

# Weekly routine
sysupdate                           # Update packages
~/dotfiles/scripts/detect-drift.sh  # Check consistency  
deep_clean                          # Clean up cruft

Before Major Changes

# Create safety snapshot
~/dotfiles/scripts/safe-update.sh

# Or manual snapshot
cp -r ~/.config ~/.config.backup

Customization

• Add machine-specific config to ~/.zshrc.local
• Add environment variables to ~/.env.local
• Never edit the main dotfiles directly for temporary changes

---

Remember: The system is designed to be invisible in daily use. If you find yourself fighting it, something may need adjustment.