@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/operations/VERSION_SYNC.md

@@ -0,0 +1,344 @@
+# Version Synchronization System
+
+The version synchronization system ensures that all version references across the repository remain consistent with the version specified in `package.json`.
+
+## Overview
+
+### Problem Statement
+Large repositories often have version numbers scattered across multiple files:
+- README badges
+- Documentation headers
+- Feature version stamps
+- Configuration files
+
+Manually keeping these synchronized is error-prone and time-consuming.
+
+### Solution Architecture
+This system provides automated version synchronization through:
+1. **CI/CD Workflow** (`.github/workflows/sync-versions.yml`) - Automated synchronization on version changes
+2. **Local Script** (`scripts/version-sync.sh`) - Manual synchronization and verification
+3. **Verification System** - Ensures all references remain consistent
+
+## Components
+
+### 1. GitHub Actions Workflow
+
+**Location**: `.github/workflows/sync-versions.yml`
+
+**Triggers**:
+- Push to `master` branch when `package.json` changes
+- Pull requests affecting `package.json`
+- Manual dispatch with optional target version
+
+**Process**:
+1. **Detect Changes** - Compares current vs previous `package.json` version
+2. **Sync Versions** - Updates all markdown files with version references
+3. **Verify Consistency** - Ensures all references match target version
+4. **Commit & Push** - Automatically commits changes (except on PRs)
+
+**Features**:
+- Backup creation before changes
+- Comprehensive change reporting
+- PR comment integration
+- Artifact preservation for rollback
+
+### 2. Local Synchronization Script
+
+**Location**: `scripts/version-sync.sh`
+
+**Usage**:
+```bash
+# Sync to current package.json version
+./scripts/version-sync.sh
+
+# Sync to specific version
+./scripts/version-sync.sh 1.2.3
+
+# Preview changes without applying
+./scripts/version-sync.sh --dry-run
+
+# Verify current consistency
+./scripts/version-sync.sh --verify
+```
+
+**Options**:
+- `--dry-run` - Preview changes without applying
+- `--verify` - Check version consistency only
+- `--backup` / `--no-backup` - Control backup creation
+- `--force` - Force sync even if no changes detected
+
+### 3. Version Patterns
+
+The system recognizes and updates these patterns:
+
+#### README.md
+```markdown
+[![Version](https://img.shields.io/badge/Version-v0.2.500-blue?style=for-the-badge)]
+```
+
+#### Documentation Files
+```markdown
+**Version**: v0.2.500
+**Dotfiles Version**: v0.2.500
+Version: v0.2.500
+version 0.2.485
+```
+
+## Integration Points
+
+### CI/CD Pipeline Integration
+
+The workflow integrates with the existing CI pipeline:
+
+```yaml
+# Existing CI workflow can depend on version sync
+needs: [sync-versions, lint-shell, test-linux]
+```
+
+### Git Hooks Integration
+
+For local development, add to `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/bash
+# Check version consistency before commits
+./scripts/version-sync.sh --verify || {
+    echo "Version inconsistency detected. Run: ./scripts/version-sync.sh"
+    exit 1
+}
+```
+
+### Package.json Integration
+
+Version changes in `package.json` automatically trigger synchronization:
+
+```json
+{
+  "name": "@sebastienrousseau/dotfiles",
+  "version": "0.2.485",  // Changes here trigger sync
+  "scripts": {
+    "version-sync": "./scripts/version-sync.sh",
+    "version-verify": "./scripts/version-sync.sh --verify"
+  }
+}
+```
+
+## Workflow Examples
+
+### Scenario 1: Version Bump
+```bash
+# Developer updates package.json version
+npm version patch
+
+# Push to master
+git push origin master
+
+# GitHub Actions automatically:
+# 1. Detects version change
+# 2. Updates all markdown files
+# 3. Commits and pushes changes
+# 4. Verifies consistency
+```
+
+### Scenario 2: PR Review
+```bash
+# PR with package.json changes
+# GitHub Actions automatically:
+# 1. Checks version consistency
+# 2. Reports any mismatches
+# 3. Comments on PR with sync status
+# 4. Provides diff preview
+```
+
+### Scenario 3: Manual Sync
+```bash
+# Local development
+./scripts/version-sync.sh --dry-run  # Preview changes
+./scripts/version-sync.sh            # Apply changes
+./scripts/version-sync.sh --verify   # Confirm consistency
+```
+
+## File Detection Logic
+
+### Automatic Discovery
+The system automatically discovers files containing version references:
+```bash
+rg -l "v?[0-9]+\.[0-9]+\.[0-9]+" --type md
+```
+
+### Known Files
+These files are always included even if they don't currently contain versions:
+- `README.md`
+- `docs/reference/FEATURES.md`
+- Any file matching version patterns
+
+### Exclusions
+Files that are intentionally excluded:
+- `CHANGELOG.md` - May contain historical versions
+- `package.json` - Source of truth
+- `docs/security/COMPLIANCE.md` - Includes external compliance spec versions
+- `docs/reference/FONTS.md` - Includes upstream font release versions
+- `docs/archive/LEGACY_ROADMAP.md` - Keeps historical release markers
+- `docs/archive/PLAN.md` - Captures multi-release planning references
+- `docs/operations/VERSION_SYNC.md` - Documentation examples and usage
+- `docs/architecture/WALKTHROUGH.md` - Contains environment-specific tag examples
+- `docs/guides/WSL2_NIX_TROUBLESHOOTING.md` - Contains IP addresses and version-like values
+- Binary files
+- Test fixtures
+
+## Error Handling
+
+### Common Issues
+
+#### Version Mismatch
+```text
+❌ Found inconsistent release in docs/reference/FEATURES.md: vX.Y.Z (expected: vA.B.C)
+```
+**Solution**: Run `./scripts/version-sync.sh` to fix
+
+#### Missing Dependencies
+```text
+❌ jq is required but not installed
+```
+**Solution**: Install dependencies (`jq`, `rg`)
+
+#### Permission Issues
+```text
+❌ Permission denied writing to README.md
+```
+**Solution**: Check file permissions and Git status
+
+### Recovery Procedures
+
+#### Rollback Changes
+```bash
+# Restore from backup
+cp .version-sync-backup/README.md.*.backup README.md
+
+# Or restore from Git
+git checkout HEAD~1 -- README.md
+```
+
+#### Force Resync
+```bash
+./scripts/version-sync.sh --force
+```
+
+## Monitoring & Maintenance
+
+### Health Checks
+```bash
+# Daily verification (add to cron)
+./scripts/version-sync.sh --verify || echo "Version drift detected"
+```
+
+### Metrics Tracking
+The GitHub Actions workflow provides metrics:
+- Files scanned
+- Files updated
+- Verification status
+- Processing time
+
+### Backup Strategy
+- Local backups in `.version-sync-backup/`
+- GitHub Actions artifacts (30-day retention)
+- Git history for rollback
+
+## Security Considerations
+
+### Token Permissions
+```yaml
+permissions:
+  contents: write      # Required for commits
+  pull-requests: write # Required for PR comments
+```
+
+### Validation
+- Version format validation (`x.y.z` pattern)
+- File path validation (no directory traversal)
+- Change verification before commit
+
+### Audit Trail
+- All changes logged in Git history
+- GitHub Actions run history
+- Backup preservation
+
+## Performance Optimization
+
+### Caching Strategy
+- Git operations use shallow fetch when possible
+- Pattern compilation cached
+- File discovery optimized with `ripgrep`
+
+### Parallel Processing
+- File processing is sequential but optimized
+- Git operations batched
+- Verification runs concurrently with updates
+
+### Resource Usage
+- Typical run time: 30-60 seconds
+- Memory usage: <100MB
+- Network usage: Minimal (only Git operations)
+
+## Future Enhancements
+
+### Planned Features
+1. **Smart Version Detection** - Semantic version awareness
+2. **Template Support** - Custom version patterns
+3. **Multi-Format Support** - YAML, JSON, TOML files
+4. **Rollback Automation** - One-command rollback
+5. **Integration Testing** - End-to-end workflow tests
+
+### Extension Points
+- Custom pattern definitions
+- File-specific update rules
+- Pre/post-sync hooks
+- External validation services
+
+## Troubleshooting
+
+### Debug Mode
+```bash
+# Enable verbose output
+DEBUG=1 ./scripts/version-sync.sh --dry-run
+```
+
+### Common Solutions
+| Issue | Solution |
+|-------|----------|
+| Script not executable | `chmod +x scripts/version-sync.sh` |
+| Missing tools | `apt install jq ripgrep` (Ubuntu) |
+| Permission denied | Check Git status and file permissions |
+| Workflow not triggering | Verify `package.json` changes are in push |
+| Changes not committed | Check branch protection rules |
+
+### Log Analysis
+```bash
+# View GitHub Actions logs
+gh run list --workflow=sync-versions.yml
+gh run view <run-id> --log
+```
+
+## Contributing
+
+### Testing Changes
+```bash
+# Test local changes
+./scripts/version-sync.sh --dry-run
+
+# Test workflow changes (requires GitHub CLI)
+gh workflow run sync-versions.yml --ref feature-branch
+```
+
+### Adding New Patterns
+1. Update pattern regex in script
+2. Add test cases
+3. Update documentation
+4. Submit PR with examples
+
+---
+
+**Last Updated**: 2026-02-15
+**Version**: v0.2.500
+**Maintainer**: Principal Automation Engineer
+**Status**: Production Ready ✅

package/docs/{ALIASES.md → reference/ALIASES.md}

@@ -1,10 +1,6 @@
 # Aliases
 
-This page lists all shell aliases that the dotfiles provide.
-
-## Organization
-
-The repo organizes aliases in `~/.dotfiles/.chezmoitemplates/aliases/` by category. Each category has its own directory containing a `<name>.aliases.sh` file.
+Shell aliases provided by the dotfiles, organized by category in `~/.dotfiles/.chezmoitemplates/aliases/`.
 
 ## Categories
 
@@ -46,7 +42,7 @@ The repo organizes aliases in `~/.dotfiles/.chezmoitemplates/aliases/` by catego
 | `di` | `docker images` | List images |
 | `dexec` | `docker exec -it` | Execute in container |
 | `denter` | `docker exec -it <container> /bin/bash` | Enter container |
-| `dlogsf` | `docker logs -f` | Follow logs |
+| `dlogsf` | `docker logs -f` | Follow logs (deprecated, use `dklf`) |
 | `dl` | `docker logs` | Show logs |
 | `dprune` | `docker system prune` | Clean up |
 | `dprunea` | `docker system prune -a` | Clean up all |

package/docs/reference/ALIASES_CHEATSHEET.md

@@ -0,0 +1,28 @@
+# Alias Cheatsheet
+
+Auto-generated from the alias manifest.
+
+## Core Shortcuts
+
+| Alias | Command |
+|-------|---------|
+| `c` | `clear_screen` |
+| `q` | `quit` |
+| `e` | `${EDITOR:-nano}` |
+| `h` | `history` |
+| `_` | `sudo ` |
+| `i` | `epoch` |
+| `l` | `dot_ls` |
+| `ll` | `dot_ll` |
+| `la` | `dot_la` |
+| `lr` | `dot_lr` |
+| `lra` | `dot_lra` |
+| `lt` | `dot_lt` |
+| `lta` | `dot_lta` |
+| `a` | `ai_core query` |
+| `d` | `dot` |
+
+## Notes
+
+- Regenerate with `dot aliases cheatsheet`.
+- Apply changes with `chezmoi apply`.

package/docs/reference/ALIASES_DEPRECATIONS.md

@@ -0,0 +1,9 @@
+# Alias Deprecations
+
+This file tracks aliases that we've kept temporarily for backwards compatibility.
+
+| Alias | Replacement | Remove In | Note |
+|-------|-------------|-----------|------|
+| `dlogsf` | `dklf` | `v0.2.500` | Removed duplicate logs-follow alias |
+
+Use `dot aliases why <alias>` to check deprecation status from the CLI.

package/docs/reference/FEATURES.md

@@ -0,0 +1,62 @@
+# Feature Flags Reference
+
+Feature flags let you turn parts of the dotfiles on or off. All flags live in `.chezmoidata.toml` under `[features]`. Set a flag to `true` to enable it, or `false` to disable it. Changes take effect after you run `dot apply`.
+
+## Shell and Terminal
+
+These flags control shell behavior and terminal tools.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `alias_wrapper` | `false` | Enable alias governance wrapper (confirms destructive aliases) |
+| `dms` | `true` | Dank Material Shell theming for GNOME |
+| `zellij` | `false` | Enable Zellij terminal multiplexer config |
+
+## Linux Desktop
+
+These flags enable Wayland desktop components. Turn them on if you run a Linux desktop with Niri or another tiling compositor.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `linux_desktop` | `false` | Enable full Linux desktop environment configs |
+| `niri` | `false` | Niri Wayland compositor config |
+| `waybar` | `false` | Waybar status bar config |
+| `fuzzel` | `false` | Fuzzel application launcher config |
+| `mako` | `false` | Mako notification daemon config |
+| `foot` | `false` | Foot terminal emulator config |
+| `kanshi` | `false` | Kanshi display manager config |
+
+## Hardware
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `touch` | `false` | Enable touchscreen support (gestures, on-screen keyboard) |
+| `t2` | `false` | Apple T2 security chip handling |
+| `surface` | `false` | Microsoft Surface hardware support |
+
+## Tool Selection
+
+| Setting | Default | Options |
+|---------|---------|---------|
+| `node_manager` | `mise` | `mise`, `fnm`, `nvm` |
+
+## Alias Policy
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `aliases.buckets.system` | `true` | Enable system utility aliases |
+| `aliases.buckets.svn` | `true` | Enable SVN aliases |
+| `aliases.policy.strict_mode` | `false` | Require confirmation for destructive aliases (rm, mv) |
+
+## How to Toggle Features
+
+You can edit flags in two places. Change `.chezmoidata.toml` in the repo to set defaults for all machines. Or override on a single machine in `~/.config/chezmoi/chezmoi.toml`:
+
+```bash
+# In ~/.config/chezmoi/chezmoi.toml
+[data.features]
+zellij = true
+linux_desktop = true
+```
+
+Then apply: `dot apply`

package/docs/reference/FONTS.md

@@ -0,0 +1,108 @@
+# Font configuration
+
+How fonts are set up, rendered, and installed in these dotfiles.
+
+## Recommended fonts
+
+### Primary: JetBrains Mono Nerd Font
+
+The default font is JetBrains Mono with Nerd Font patches. It's designed for code readability, supports ligatures, includes Powerline/Nerd Font glyphs, and clearly distinguishes similar characters (`0`/`O`, `1`/`l`/`I`).
+
+### Alternatives
+
+| Font | Style | Best for |
+|------|-------|----------|
+| Fira Code | Modern | Ligature fans |
+| Cascadia Code | Microsoft | VS Code users |
+| Hack | Classic | Traditional monospace look |
+| Source Code Pro | Adobe | Clean aesthetic |
+| Iosevka | Narrow | Small screens |
+
+## Installation
+
+### macOS (Homebrew)
+
+```bash
+brew tap homebrew/cask-fonts
+brew install --cask font-jetbrains-mono-nerd-font
+
+# Or use the dot CLI
+dot fonts install
+```
+
+### Linux (manual)
+
+```bash
+wget https://github.com/ryanoasis/nerd-fonts/releases/download/v3.4.0/JetBrainsMono.zip
+unzip JetBrainsMono.zip -d ~/.local/share/fonts/
+fc-cache -fv
+```
+
+### Patching your own fonts
+
+To patch a custom font with Nerd Font glyphs:
+
+```bash
+~/.dotfiles/scripts/fonts/patch-fonts.sh /path/to/font.ttf
+```
+
+## Terminal configuration
+
+### Ghostty
+
+```text
+font-family = JetBrains Mono Nerd Font
+font-size = 14
+```
+
+### WezTerm
+
+```lua
+config.font = wezterm.font("JetBrains Mono Nerd Font")
+config.font_size = 14.0
+```
+
+### Alacritty
+
+```yaml
+font:
+  normal:
+    family: JetBrains Mono Nerd Font
+  size: 14.0
+```
+
+### Kitty
+
+```text
+font_family JetBrains Mono Nerd Font
+font_size 14.0
+```
+
+## Font size recommendations
+
+| Display | Size |
+|---------|------|
+| 13" laptop | 12-13pt |
+| 15" laptop | 13-14pt |
+| 24" monitor | 14-15pt |
+| 27" 4K monitor | 15-16pt |
+
+## Troubleshooting
+
+### Fonts not displaying correctly
+
+1. Verify the font is installed: `fc-list | grep JetBrains`
+2. Restart your terminal
+3. Double-check the terminal's font settings
+
+### Nerd Font icons missing
+
+1. Make sure you're using a Nerd Font variant (not the plain version)
+2. Confirm the terminal supports the required Unicode range
+3. Try a different Nerd Font if the issue persists
+
+### Ligatures not working
+
+1. Enable ligatures in your terminal's settings
+2. Some terminals don't support ligatures (e.g., `Terminal.app`)
+3. Ghostty, WezTerm, and Kitty all handle ligatures well

package/docs/reference/PROFILES.md

@@ -0,0 +1,65 @@
+# Profiles and Machine Setup
+
+## Profile System
+
+You can set up each machine differently using profiles and hardware presets.
+
+### Setting Your Profile
+
+Edit `~/.config/chezmoi/chezmoi.toml`:
+
+```toml
+[data]
+profile = "laptop"        # laptop | minimal | server
+machine = "macbook-m3"    # optional: machine identifier
+```
+
+### Available Profiles
+
+| Profile | Description | What's Included |
+|---------|-------------|-----------------|
+| `laptop` | Full desktop setup (default) | All tools, AI CLIs, themes, completions |
+| `minimal` | Fast, lightweight | Core shell, git, basic aliases only |
+| `server` | Headless server | Shell, git, monitoring tools, no desktop |
+
+### Per-Machine Overrides
+
+Create a `~/.config/chezmoi/chezmoi.toml` file on each machine to override defaults:
+
+```toml
+[data]
+profile = "laptop"
+machine = "work-macbook"
+default_shell = "zsh"
+
+[data.features]
+linux_desktop = false
+zellij = true
+```
+
+### Hardware Presets
+
+The `templates/chezmoi-data/` folder has ready-made configs for common hardware:
+
+- `mac-m1.toml.example` — Apple Silicon MacBook
+- `geekom-a9.toml.example` — AMD mini PC (Linux)
+- `surface-pro-7p.toml.example` — Microsoft Surface (Linux)
+- `mac-t2-linux.toml.example` — Intel Mac running Linux
+
+Copy the one that matches your hardware:
+
+```bash
+cp templates/chezmoi-data/mac-m1.toml.example ~/.config/chezmoi/chezmoi.toml
+chezmoi apply
+```
+
+### Environment Variables
+
+You can change behavior for a single session without editing any files:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `DOTFILES_FAST=1` | 0 | Skip heavy layers (zinit, completions) |
+| `DOTFILES_ULTRA_FAST=1` | 0 | Bare minimum shell (aliases + prompt) |
+| `DOTFILES_AI=1` | 0 | Enable AI helper scripts |
+| `DOTFILES_PROFILE=custom` | laptop | Override profile for session |