@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/STRUCTURE.md

@@ -1,102 +0,0 @@
-# Repository Structure
-
-This document maps every top-level path in the repository to its
-purpose. Skim it once and you should be able to answer:
-
-- **Where is the `dot` CLI?** → `bin/dot` (the source-of-truth file). At runtime it lives at `~/.local/bin/dot`.
-- **Why are there 20+ `dot_*` files at root?** → chezmoi convention: a `dot_X` source file deploys to `~/.X` on apply. Same for `executable_*` (gains `+x`), `private_*` (`0600`), `run_onchange_*` (re-runs when source changes).
-- **What's the framework vs. the maintainer's personal config?** → Everything under `scripts/`, `install/`, `tools/`, `lib/`, and `defaults/.chezmoitemplates/` is framework code. Everything under `defaults/dot_config/`, `defaults/dot_warp/`, `defaults/private_dot_ssh/` is user-facing default configuration (chezmoi auto-rebases via `.chezmoiroot`).
-
-The Debian/aws-cli-style root layout shipped in **v0.2.503**:
-`bin/` (dispatcher), `lib/` (shared bash libs), `defaults/`
-(all chezmoi-tracked source files, rebased via
-`.chezmoiroot`). Repo root now hosts only project/CI/docs paths.
-See `docs/operations/ROADMAP_V0_2_503.md` for the full history.
-
----
-
-## Top-level paths
-
-| Path | Kind | Purpose |
-|------|------|---------|
-| **CLI + framework** | | |
-| `dot_local/bin/` | framework | `executable_dot` (CLI entrypoint) and helper scripts. Deploys to `~/.local/bin/`. |
-| `dot_local/share/` | framework | Man pages, zsh completions. Deploys to `~/.local/share/`. |
-| `scripts/` | framework | Runtime-invoked scripts (`dot` CLI dispatch + specialised subtrees). See `scripts/README.md`. |
-| `tools/` | repo-ops | Repo-only ops: CI helpers, release, maintenance, docs-generation. Not distributable. See `tools/README.md`. |
-| `lib/dot/` | framework | Shared bash library sourced by every `dot` subcommand and the dispatcher. Reorganised here from `scripts/dot/lib/` per RFC Phase 1. See `lib/dot/README.md`. |
-| `lib/` | framework | Library tree (`lib/dot/` + third-party `lib/wasm-tools/`). |
-| `install/` | framework | Bootstrap logic + distribution-channel manifests (`homebrew/`, `scoop/`, `aur/`). See `install/README.md`. `install/provision/` runs on `chezmoi apply` via `run_onchange_*` triggers. |
-| `install.sh` | framework | Top-level installer. SHA256-verified chezmoi fetch + initial apply. |
-| `.chezmoitemplates/` | framework | Reusable Go-template partials (aliases, functions, paths). Sourced by `dot_*.tmpl` files. |
-| **User-facing defaults** | | |
-| `dot_bashrc`, `dot_zshrc`, `dot_zshenv`, `dot_zprofile`, `dot_profile`, `dot_vimrc`, etc. | defaults | Shell + editor rc files. Deploy to `~/.X`. |
-| `dot_config/` | defaults | XDG config (`~/.config/*`). Largest tree — 80+ tool configs. |
-| `dot_local/` (non-bin/share) | defaults | Per-user state files for tools (`dot_local/state/`, etc.). |
-| `dot_cargo/`, `dot_etc/`, `dot_warp/` | defaults | Tool-specific roots (cargo, system etc, Warp terminal). |
-| `private_dot_ssh/` | defaults | SSH config — chezmoi `private_` prefix forces 0600. Does NOT contain private keys. |
-| `dot_claude/` | defaults | Claude Code per-user skills and config. |
-| **Templates + data** | | |
-| `templates/` | framework | Non-chezmoi templates (e.g. for `dot agents render`). |
-| `.chezmoidata/` | data | Hardware presets (`macbook-t2`, `surface-pro`) read by templates. |
-| `.chezmoidata.toml` | data | Feature flags + version. Single source-of-truth for `dotfiles_version`. |
-| `.chezmoi.toml.tmpl` | framework | Per-host chezmoi config generated on first apply. |
-| `.chezmoiignore` / `.chezmoiignore.tmpl` | framework | Tells chezmoi which paths NOT to deploy. |
-| **Docs + tests** | | |
-| `docs/` | docs | All documentation: `manual/` (user guide), `operations/` (audits, roadmaps), `reference/` (lookup tables), `security/`. |
-| `tests/` | tests | Test suite: `framework/` (runner + assertions + mocks), `unit/`, `integration/`, `regression/`, `fuzz/`, `snapshots/`. |
-| `examples/` | docs | Standalone examples (mise plugin, AI patterns, ops scripts). |
-| **CI + release** | | |
-| `.github/` | ci | GitHub Actions workflows + issue/PR templates + repo-level SECURITY/CODEOWNERS. |
-| `.devcontainer/` | ci | Dev Container spec for reproducible contributor onboarding. |
-| `Dockerfile.test` | ci | Container baseline for the CI test job. |
-| `.pre-commit-config.yaml` → `config/pre-commit-config.yaml` | ci | Pre-commit hooks (shellcheck, shfmt, luacheck, gitleaks, typos, conventional-commits). |
-| `flake.nix` / `flake.lock` | ci | Nix flake for reproducible dev shell. |
-| `mise.toml` / `mise-versions.lock.json` | ci | Pinned tool versions (mise as the package manager). |
-| **Misc + agents** | | |
-| `AGENTS.md` | docs | Cross-harness AI agent context (the standard read by Codex/Cursor/etc.). |
-| `.cursor/`, `.codex/`, `.windsurf/`, `.zed/`, `.roo/`, `.clinerules`, `.aider.conf.yml`, `.continuerc.json`, `.jules/`, `.agy/` | agents | Per-harness AGENTS.md renderings. Generated by `dot agents render`. Each one points back at `CLAUDE.md` as canonical. |
-| `CLAUDE.md` | docs | Project guidelines (the canonical source — `dot agents render` propagates it). |
-| `CONTRIBUTING.md` | docs | Contributor guide (must stay at root for GitHub auto-discovery). |
-| `docs/CONFIG_STRATEGY.md`, `docs/OPENCODE.md` | docs | Strategy + OpenCode-CLI guidance. Moved out of root for cleanliness in v0.2.503. |
-| `README.md` / `CHANGELOG.md` / `LICENSE` | docs | Standard project files. |
-| `Justfile.tmpl` / `Makefile` | dev | Task runners. |
-| `dist/` | build | Build artefacts directory. |
-| `coverage/`, `nightly-reports/` | build | CI output directories (gitignored). |
-| `nix/` | build | Nix flake source. |
-| `.well-known/` | misc | RFC-compliant `.well-known/` content (currently used for WKD GPG key publication). |
-| `.version-sync-backup/` | misc | Backup directory used by `scripts/version-sync.sh` during release prep. |
-
-## Chezmoi naming contract
-
-| Prefix / suffix | Effect on deployment |
-|---|---|
-| `dot_foo` | Deploys as `.foo` (the `dot_` is consumed). |
-| `executable_foo` | Adds `+x` permission. |
-| `private_foo` | Sets `0600` permission. |
-| `run_onchange_foo.sh` | Script re-executes when its hash changes. |
-| `*.tmpl` | Processed as a Go template with chezmoi data before deployment. |
-
-**Critical gotcha:** `executable_dot_foo` deploys as `.foo` (not
-`dot_foo`). The `dot_` prefix is consumed by chezmoi after the
-`executable_` prefix. Renaming a deployed file silently can leave
-stale state in `~/.config/chezmoi/`.
-
-## Where to make changes
-
-| Goal | File(s) to edit |
-|------|----------------|
-| Add a new `dot <subcommand>` | `scripts/dot/commands/<subcommand>.sh` + dispatch in `bin/dot` + entry in `docs/manual/03-reference/01-dot-cli.md` + entry in `docs/manual/command-index.md`. |
-| Change an alias | `.chezmoitemplates/aliases/<file>.aliases.sh` (sourced by `dot_zshrc.tmpl`, etc.). |
-| Add a feature flag | `[features]` block in `.chezmoidata.toml` + doc entry in `docs/manual/03-reference/05-feature-flags.md`. |
-| Add a new file deployed to `~/.X` | Create `dot_X` at root (or under a chezmoi-managed subtree). |
-| Add a new chezmoi template | `dot_X.tmpl` at root, then use `{{ }}` for chezmoi data. |
-| Add a CI workflow | `.github/workflows/<name>.yml`. |
-| Add a test | `tests/unit/<domain>/test_<name>.sh` or `tests/integration/test_<name>.sh`. |
-
-## See also
-
-- `scripts/README.md` — map of the `scripts/` subtree.
-- `CONTRIBUTING.md` — code-style + commit-message + signing requirements.
-- `CLAUDE.md` — AI-assistant guidelines (the canonical source for `dot agents render`).
-- `docs/operations/ROADMAP_V0_2_503.md` — current release scope, including the v0.2.503 reorganisation plan.

package/docs/adr/ADR-001-ci-cd-pipeline.md

@@ -1,118 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# ADR-001: Multi-stage CI/CD Pipeline Design
-
-**Status**: Accepted
-**Date**: 2026-02-09
-**Authors**: @sebastienrousseau
-
-## Context
-
-The dotfiles repository requires a CI/CD pipeline that:
-
-- Validates changes across multiple platforms (Linux, macOS)
-- Runs security scans to detect secrets and vulnerabilities
-- Tests shell scripts, Lua configurations, and Nix expressions
-- Maintains fast feedback loops for developers
-- Minimizes GitHub Actions costs (runner minutes)
-
-Traditional approaches run all checks on every commit, leading to:
-
-- Wasted compute on unrelated changes (e.g., running Lua linting when only docs change)
-- High costs from macOS runners ($0.08/min vs $0.008/min for Linux)
-- Long feedback times from sequential job execution
-
-## Decision
-
-Implement a **5-stage progressive CI pipeline** with path-based filtering:
-
-### Stage 1: Change Detection
-
-Use `dorny/paths-filter` to detect which file categories changed:
-
-- `shell`: *.sh, scripts/**, install/**
-- `lua`: dot_config/nvim/**, *.lua
-- `nix`: nix/**, *.nix
-- `config`: dot_*/**, .chezmoitemplates/**
-
-### Stage 2: Lint (Parallel, Conditional)
-
-- **lint-shell**: Only runs if shell files changed
-- **lint-lua**: Only runs if Lua files changed
-- Run in parallel to minimize wall-clock time
-
-### Stage 3: Security (Always on PRs)
-
-- **secrets-scan**: Gitleaks on every PR (critical)
-- **link-check**: Only on schedule (expensive)
-
-### Stage 4: Test (Conditional Matrix)
-
-- Linux-only for PRs (cheapest)
-- Full matrix (Linux + macOS) on schedule/manual trigger
-- Docker container tests for installation validation
-
-### Stage 5: Quality (Schedule/Manual Only)
-
-- Idempotency verification
-- Performance benchmarks
-- Nix flake checks
-
-### Cost Optimization Strategies
-
-1. **Path filters**: Skip jobs when files don't match
-2. **Concurrency groups**: Cancel in-progress runs on new pushes
-3. **Conditional matrices**: Expensive OS testing only on schedule
-4. **Aggressive caching**: Tools, dependencies, databases
-
-## Consequences
-
-### Positive
-
-- ~50% reduction in GitHub Actions minutes
-- Fast feedback for most changes (1-3 minutes)
-- Comprehensive testing still available via schedule/manual
-- Clear separation of concerns between stages
-
-### Negative
-
-- Complexity in workflow configuration
-- Some bugs might only surface in scheduled runs
-- Path filter maintenance required as repo structure evolves
-
-### Neutral
-
-- Developers can trigger full CI manually with `workflow_dispatch`
-- Breaking changes to CI require testing across all stages
-
-## Implementation
-
-```yaml
-# Key patterns used
-on:
-  push:
-    paths:
-      - '**.sh'  # Only trigger on shell changes
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  changes:
-    outputs:
-      shell: ${{ steps.filter.outputs.shell }}
-
-  lint-shell:
-    needs: changes
-    if: needs.changes.outputs.shell == 'true'
-```
-
-## References
-
-- [GitHub Actions Path Filtering](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)
-- [dorny/paths-filter](https://github.com/dorny/paths-filter)
-{% endraw %}

package/docs/adr/ADR-002-shell-performance.md

@@ -1,130 +0,0 @@
----
-render_with_liquid: false
----
-
-# ADR-002: Shell Performance Optimization Strategy
-
-**Status**: Accepted
-**Date**: 2026-02-09
-**Authors**: @sebastienrousseau
-
-## Context
-
-Shell startup time directly impacts developer productivity. Every new terminal,
-tmux pane, or shell command execution incurs this cost. With rich shell
-configurations (completions, prompts, plugins), startup can easily exceed 1-2
-seconds.
-
-Goals:
-
-- Target startup time: <500ms for interactive shells
-- Maintain full functionality (completions, syntax highlighting, git info)
-- Support both zsh and bash
-- Work across macOS and Linux
-
-## Decision
-
-Implement a **multi-layer performance optimization strategy**:
-
-### Layer 1: Compilation and Caching
-
-```bash
-# Compile zsh files to .zwc format
-_cached_eval() {
-  local cache="$HOME/.cache/zsh/$1.zwc"
-  if [[ ! -f "$cache" || "$2" -nt "$cache" ]]; then
-    eval "$($2)" > "$cache.tmp"
-    zcompile "$cache.tmp" "$cache"
-  fi
-  source "$cache"
-}
-```
-
-- Compile frequently-sourced files to bytecode
-- Cache command output (brew shellenv, mise activate)
-- Invalidate cache when source files change
-
-### Layer 2: Lazy Loading
-
-Defer loading of heavy components until first use:
-
-```bash
-# Lazy load completions
-function kubectl() {
-  unfunction kubectl
-  source <(kubectl completion zsh)
-  kubectl "$@"
-}
-```
-
-- Completions loaded on first command use
-- NVM/RVM loaded only when node/ruby commands invoked
-- Heavy plugins deferred via zinit's `wait` modifier
-
-### Layer 3: Zinit Turbo Mode
-
-```zsh
-zinit ice wait lucid
-zinit light zsh-users/zsh-autosuggestions
-```
-
-- Plugins load asynchronously after prompt
-- Critical plugins (syntax highlighting) load synchronously
-- Most plugins have 0ms impact on startup
-
-### Layer 4: Conditional Loading
-
-```bash
-# Only load if command exists
-[[ -x /opt/homebrew/bin/brew ]] && eval "$(/opt/homebrew/bin/brew shellenv)"
-
-# Skip in non-interactive shells
-[[ $- != *i* ]] && return
-```
-
-- Platform-specific code guarded by OS detection
-- Heavy features opt-in via environment variables
-- Non-interactive shells get minimal config
-
-### Monitoring
-
-Benchmark script to track startup time:
-
-```bash
-hyperfine --warmup 3 --runs 10 "zsh -i -c exit"
-```
-
-CI enforces 500ms threshold with warnings.
-
-## Consequences
-
-### Positive
-
-- Consistent <500ms startup across platforms
-- Full functionality preserved
-- Easy to add new tools without performance regression
-- Clear patterns for contributors to follow
-
-### Negative
-
-- First invocation of lazy-loaded commands is slower
-- Cache invalidation bugs can cause stale behavior
-- Complexity in understanding load order
-
-### Neutral
-
-- Profiling required when adding new plugins
-- Trade-off between convenience and performance explicit
-
-## Measurements
-
-| Configuration | Startup Time |
-|---------------|--------------|
-| Vanilla zsh | ~50ms |
-| With oh-my-zsh | ~800ms |
-| This approach | ~200-400ms |
-
-## References
-
-- [Zsh Startup Optimization](https://htr3n.github.io/2018/07/faster-zsh/)
-- [Zinit Turbo Mode](https://zdharma-continuum.github.io/zinit/wiki/INTRODUCTION/)

package/docs/adr/ADR-003-security-first.md

@@ -1,158 +0,0 @@
----
-render_with_liquid: false
----
-
-# ADR-003: Security-First Approach
-
-**Status**: Accepted
-**Date**: 2026-02-09
-**Authors**: @sebastienrousseau
-
-## Context
-
-Dotfiles repositories present unique security challenges:
-
-- They configure system behavior and permissions
-- They may contain or reference secrets (API keys, tokens)
-- They execute scripts with user privileges
-- They're often cloned to multiple machines
-
-A security breach in dotfiles can compromise all systems using them.
-
-## Decision
-
-Implement a **defense-in-depth security model** with multiple layers:
-
-### Layer 1: Secrets Protection
-
-**Never commit secrets:**
-
-```bash
-# .gitleaks.toml - block common secret patterns
-[[rules]]
-id = "generic-api-key"
-regex = '''(?i)(api[_-]?key|apikey)\s*[:=]\s*['"]?([a-zA-Z0-9]{20,})'''
-```
-
-**Encrypted secrets with age:**
-
-```bash
-# Secrets stored encrypted, decrypted at apply time
-chezmoi.encryption = "age"
-chezmoi.age.identity = "~/.config/chezmoi/key.txt"
-```
-
-**CI enforcement:**
-
-- Gitleaks runs on every PR
-- TruffleHog for verified secrets detection
-- Block merge if secrets detected
-
-### Layer 2: Input Validation
-
-**Path traversal prevention:**
-
-```bash
-# Validate all user inputs
-if [[ ! "$template_lang" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-  die "Invalid template name: $template_lang"
-fi
-```
-
-**Safe file operations:**
-
-```bash
-# Use absolute paths, validate before operations
-local real_path
-real_path="$(realpath -m "$user_input")"
-if [[ "$real_path" != "$allowed_base"/* ]]; then
-  die "Path outside allowed directory"
-fi
-```
-
-### Layer 3: Opt-in System Modifications
-
-**Dangerous operations require explicit consent:**
-
-```bash
-# Security scripts are opt-in
-if [ "${DOTFILES_SECURITY:-0}" != "1" ]; then
-  echo "Security hardening is opt-in. Set DOTFILES_SECURITY=1 to enable."
-  exit 0
-fi
-```
-
-**Comprehensive logging:**
-
-```bash
-# All system modifications logged
-log_security_change() {
-  echo "[$(date -Iseconds)] $1" >> "$HOME/.local/share/dotfiles-security.log"
-}
-```
-
-### Layer 4: CI Security Scanning
-
-**Multi-tool approach:**
-
-- **Gitleaks**: Secrets in git history
-- **Shellcheck**: Shell script vulnerabilities
-- **Checkov**: Infrastructure misconfigurations
-- **Trivy**: Container vulnerabilities (when applicable)
-- **CodeQL**: Static analysis for Python/JavaScript
-
-**Weekly deep scans:**
-
-```yaml
-schedule:
-  - cron: '0 2 * * 0'  # Weekly security audit
-```
-
-### Layer 5: Minimal Privileges
-
-**Scripts request only needed permissions:**
-
-```bash
-# Don't run as root unless necessary
-if [ "$(id -u)" = "0" ]; then
-  die "This script should not run as root"
-fi
-
-# Use sudo only for specific commands
-sudo sysctl -w net.ipv4.tcp_keepalive_time=60
-```
-
-## Consequences
-
-### Positive
-
-- Secrets never enter git history
-- System modifications are auditable
-- Multiple layers catch different vulnerability types
-- Contributors have clear security patterns to follow
-
-### Negative
-
-- Additional complexity in scripts
-- Encrypted secrets require key management
-- Some features disabled by default (friction)
-
-### Neutral
-
-- Security vs convenience trade-offs explicit
-- Regular security audits via scheduled CI
-
-## Security Checklist for Contributors
-
-- [ ] No hardcoded secrets (use environment variables or age encryption)
-- [ ] Validate all user inputs
-- [ ] Use absolute paths for file operations
-- [ ] Document any system modifications
-- [ ] Test scripts with shellcheck
-- [ ] Add appropriate permission checks
-
-## References
-
-- [OWASP Secure Coding Practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/)
-- [Age Encryption](https://github.com/FiloSottile/age)
-- [Gitleaks](https://github.com/gitleaks/gitleaks)

package/docs/adr/ADR-004-cli-architecture.md

@@ -1,171 +0,0 @@
----
-render_with_liquid: false
----
-
-# ADR-004: Chezmoi + Custom CLI Wrapper Architecture
-
-**Status**: Accepted
-**Date**: 2026-02-09
-**Authors**: @sebastienrousseau
-
-## Context
-
-Managing dotfiles requires:
-
-- Tracking file changes and applying them consistently
-- Handling platform-specific configurations
-- Supporting encrypted secrets
-- Providing a good developer experience
-
-Options considered:
-
-1. **Bare git repository**: Simple but poor UX, no templating
-2. **GNU Stow**: Symlink-based, limited features
-3. **Chezmoi only**: Powerful but complex CLI
-4. **Custom from scratch**: High maintenance burden
-5. **Chezmoi + wrapper**: Best of both worlds
-
-## Decision
-
-Use **Chezmoi as the core engine** with a **custom `dot` CLI wrapper** that:
-
-### Architecture
-
-```text
-┌─────────────────────────────────────────────┐
-│                 dot CLI                      │
-│  (User-friendly interface, custom commands)  │
-├─────────────────────────────────────────────┤
-│              Command Modules                 │
-│  core │ diagnostics │ tools │ appearance    │
-│  secrets │ security │ meta                   │
-├─────────────────────────────────────────────┤
-│              Shared Library                  │
-│  utils.sh (resolve_source_dir, run_script)  │
-├─────────────────────────────────────────────┤
-│                 Chezmoi                      │
-│  (Template engine, state management, apply)  │
-└─────────────────────────────────────────────┘
-```
-
-### Core Principles
-
-**1. Chezmoi handles complexity:**
-
-- Template rendering with Go text/template
-- Encrypted secrets with age
-- State tracking (what's applied vs source)
-- Cross-platform path handling
-
-**2. dot CLI handles UX:**
-
-- Memorable command names (`dot sync` vs `chezmoi apply`)
-- Domain-specific commands (`dot doctor`, `dot theme`)
-- Integration with external tools (Nix, Docker, Neovim)
-- Consistent help and error messages
-
-**3. Modular command structure:**
-
-```text
-scripts/dot/
-├── lib/
-│   └── utils.sh          # Shared functions
-└── commands/
-    ├── core.sh           # apply, sync, update, add, diff
-    ├── diagnostics.sh    # doctor, heal, health, benchmark
-    ├── tools.sh          # tools, new, packages
-    ├── appearance.sh     # theme, wallpaper, fonts
-    ├── secrets.sh        # secrets-init, secrets
-    ├── security.sh       # firewall, backup, encrypt-check
-    └── meta.sh           # upgrade, docs, learn
-```
-
-**4. Delegation pattern:**
-
-```bash
-# Main dispatcher in dot CLI
-dispatch() {
-  local module="$1" cmd="$2"
-  shift 2
-  exec bash "$src_dir/scripts/dot/commands/$module.sh" "$cmd" "$@"
-}
-```
-
-### Chezmoi Integration Points
-
-| Feature | Chezmoi | dot CLI |
-|---------|---------|---------|
-| Apply changes | `chezmoi apply` | `dot sync` |
-| View diff | `chezmoi diff` | `dot diff` |
-| Edit secrets | `chezmoi edit --encrypted` | `dot secrets` |
-| Source directory | `chezmoi source-path` | `dot cd` |
-| Health check | `chezmoi doctor` | `dot doctor` (extended) |
-
-### Extension Points
-
-Custom commands can:
-
-1. Wrap chezmoi commands with better defaults
-2. Add entirely new functionality (benchmarks, themes)
-3. Integrate with system tools (nix, docker, brew)
-4. Provide interactive experiences (tour, learn)
-
-## Consequences
-
-### Positive
-
-- Leverage Chezmoi's battle-tested engine
-- User-friendly interface for common tasks
-- Easy to add domain-specific commands
-- Modular structure enables testing and maintenance
-- Single entry point (`dot`) for all operations
-
-### Negative
-
-- Two layers to understand (chezmoi + dot)
-- Version coupling between chezmoi and scripts
-- Some chezmoi features not exposed via dot
-
-### Neutral
-
-- Advanced users can still use chezmoi directly
-- Documentation needed for both layers
-- Upgrade path when chezmoi adds new features
-
-## Implementation Notes
-
-### Adding a New Command
-
-1. Identify the appropriate module (or create new one)
-2. Add function `cmd_<name>()` to module
-3. Add case to module's dispatch
-4. Add case to main dot CLI dispatcher
-5. Update help text
-6. Add tests if complex
-
-### Module Template
-
-```bash
-#!/usr/bin/env bash
-# Dotfiles CLI - <Category> Commands
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/../lib/utils.sh"
-
-cmd_example() {
-  # Implementation
-}
-
-case "${1:-}" in
-  example) shift; cmd_example "$@" ;;
-  *) echo "Unknown command: ${1:-}" >&2; exit 1 ;;
-esac
-```
-
-## References
-
-- [Chezmoi Documentation](https://www.chezmoi.io/)
-- [Command Pattern](https://refactoring.guru/design-patterns/command)
-- [Unix Philosophy](https://en.wikipedia.org/wiki/Unix_philosophy)