@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/README.md

@@ -0,0 +1,82 @@
+---
+render_with_liquid: false
+---
+
+# Documentation
+
+Start here. Then go deeper.
+
+## The Manual
+
+The complete reference is the `.dotfiles` Manual — a multi-format book covering every concept, tutorial, reference, and recipe.
+
+- Online: <https://sebastienrousseau.github.io/dotfiles/manual/> (HTML, PDF, EPUB, ASCII)
+- Locally: `dot manual` opens the HTML in your browser
+- Sources: [`docs/manual/`](manual/)
+
+Quick jumps into the Manual:
+
+- [Introduction](manual/00-introduction.md) — who, what, how
+- [Concepts](manual/01-concepts/) — architecture, trust model, theme engine, fleet, self-healing
+- [Tutorials](manual/02-tutorials/) — first install, wallpaper→theme, profiles, secrets, fleet
+- [Reference](manual/03-reference/) — CLI, config files, environment, templates, feature flags
+- [Cookbook](manual/04-cookbook/) — 40+ recipes, troubleshooting, FAQ
+
+## Start
+
+- [Install](guides/INSTALL.md)
+- [Troubleshooting](guides/TROUBLESHOOTING.md)
+- [Support matrix](reference/SUPPORT_MATRIX.md)
+
+## Daily use
+
+- [Utilities and `dot` CLI](reference/UTILS.md)
+- [Operations](operations/OPERATIONS.md)
+- [Trusted agent workstation](operations/TRUSTED_AGENT_WORKSTATION.md)
+- [Workstation attestation](operations/ATTESTATION.md)
+- [Interoperability](architecture/INTEROP.md)
+- [Agent interoperability](interop/A2A.md)
+- [AI integrations](AI.md)
+
+## Security and trust
+
+- [Security overview](security/SECURITY.md)
+- [Security checklist](security/SECURITY_CHECKLIST.md)
+- [Policy bundle releases](security/POLICY_RELEASES.md)
+- [Secrets](security/SECRETS.md)
+- [Compliance](security/COMPLIANCE.md)
+- [Threat model](security/THREAT_MODEL.md)
+
+## Build and maintain
+
+- [Testing](operations/TESTING.md)
+- [Reliability](operations/RELIABILITY.md)
+- [Naming conventions](NAMING_CONVENTIONS.md)
+- [Architecture](architecture/ARCHITECTURE.md)
+- [Repository layout](architecture/REPO_LAYOUT.md)
+- [Architecture decisions](adr/README.md)
+
+## Repository map
+
+| Path | Purpose |
+| :--- | :--- |
+| `docs/` | Guides, reference, security, and architecture |
+| `scripts/` | Repo-only scripts and `dot` command internals |
+| `install/` | Installer and provisioning helpers |
+| `dot_config/` | Managed user configuration files |
+| `dot_local/` | Managed local executables |
+| `examples/` | Executable examples |
+| `tests/` | Unit, integration, and framework coverage |
+
+## Platform guides
+
+- [WSL2 and Nix](guides/WSL2_NIX_TROUBLESHOOTING.md)
+- [Neovim IDE](guides/NEOVIM_IDE_GUIDE.md)
+
+## Reference
+
+- [Features](reference/FEATURES.md)
+- [Tools](reference/TOOLS.md)
+- [Aliases](reference/ALIASES.md)
+- [Roadmap](operations/ROADMAP.md)
+- [Version sync](operations/VERSION_SYNC.md)

package/docs/_config.yml

@@ -0,0 +1,59 @@
+title: ".dotfiles"
+description: "Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL — published at doc.dotfiles.io."
+url: "https://doc.dotfiles.io"
+baseurl: ""
+
+# Jekyll renders this site from docs/ — see .github/workflows/pages.yml.
+# Theme is the GitHub-hosted Cayman skin (zero-Gemfile setup); switch to
+# `remote_theme: just-the-docs/just-the-docs` later if a richer
+# navigation/search UX is wanted (requires plugin allowlist update on
+# GH Pages side).
+theme: jekyll-theme-cayman
+
+plugins:
+  - jekyll-relative-links
+  - jekyll-seo-tag
+  - jekyll-sitemap
+  - jekyll-redirect-from
+  # Renders `README.md` as the directory index where present (matches
+  # the GitHub-browse experience for users coming from the repo links
+  # in docs/index.md).
+  - jekyll-readme-index
+
+relative_links:
+  enabled: true
+  collections: true
+
+# Treat *.md as pages so cross-page links work without trailing-slash
+# kludges; include CNAME so the published artifact preserves it across
+# workflow deploys.
+include:
+  - CNAME
+  - .well-known
+
+exclude:
+  - "*.tmpl"
+  - "manual/_toc.yml"
+  - "scripts/"
+  - "Gemfile"
+  - "Gemfile.lock"
+  - "vendor/"
+
+markdown: kramdown
+kramdown:
+  input: GFM
+  syntax_highlighter: rouge
+  hard_wrap: false
+
+# Many of our docs include chezmoi/Go-template snippets like
+# `{{ .variable }}` inside fenced code blocks. Liquid runs BEFORE
+# kramdown sees those fences and would try to resolve the placeholders
+# as Liquid expressions (silently dropping them from the output). Each
+# .md file therefore carries explicit `render_with_liquid: false` in
+# its frontmatter — a site-wide default in this block was not honored
+# reliably, so we keep the kill-switch per-page instead.
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default

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

@@ -0,0 +1,118 @@
+---
+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

@@ -0,0 +1,130 @@
+---
+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

@@ -0,0 +1,158 @@
+---
+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)