dotfiles/USAGE.md

# Dotfiles Usage Guide

## Quick Start

### Initial Deployment
```bash
# 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
```bash
# 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:
```bash
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:
```bash
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)
```bash
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
```bash
gst                    # Enhanced git status with context
gco                    # Smart git checkout with branch suggestions
gp                     # Push with upstream tracking
```

### Development Tools

#### Quick Navigation
```bash
z pattern              # Zoxide smart directory jumping
..                     # Go up one directory
...                    # Go up two directories  
....                   # Go up three directories
```

#### File Operations
```bash
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:
```bash
~/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:
```bash
~/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:
```bash
# 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:
```bash
# 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:
```bash
~/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:

```bash
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`:
```bash
# 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:
```bash
# 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
```bash
# Check for syntax errors
zsh -n ~/.zshrc

# Load with debugging
zsh -x ~/.zshrc
```

#### Missing Tools
```bash
# Install missing Homebrew packages
brew bundle --file=~/dotfiles/Brewfile

# Check for available updates
brew outdated
```

#### Performance Issues
```bash
# Check shell load time
time (zsh -i -c exit)

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

#### Configuration Drift
```bash
# Detect and fix drift
~/dotfiles/scripts/detect-drift.sh

# Re-sync configurations
~/dotfiles/engage config
```

### Recovery Procedures

#### System Rollback
If updates break the system:
```bash
# View available snapshots
ls ~/.system-snapshots/

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

#### Configuration Reset
```bash
# Backup current config
cp ~/.zshrc ~/.zshrc.backup

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

## Best Practices

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

### Before Major Changes
```bash
# 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.*