Add comprehensive system enhancements and shell configurations
Following the μέτρον principle of durable, thoughtful solutions: Shell Configuration: - Add refined .zshrc with modular architecture - Include .p10k.zsh for Powerlevel10k prompt - Add .zprofile for login shell configuration - Update aliases with new dotfiles management tools System Management Tools: - safe-update.sh: System updates with rollback protection - detect-drift.sh: Configuration drift detection - system-health.sh: Comprehensive health monitoring - generate-lockfile.sh: Version tracking for reproducibility Documentation: - ARCHITECTURE.md: Philosophy and design rationale - USAGE.md: Practical guide and troubleshooting Other Updates: - Update symlinks.sh to manage all config files - Add .vimrc configuration - Create Brewfile.lock for version pinning These enhancements provide visibility, safety, and maintainability while following the prime directive of prioritizing durability. 🖖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
David F Glidden
co-authored by
Claude
Claude
parent
92b0ead991
commit
1f543d195b
@@ -0,0 +1,333 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user