@sebastienrousseau/dotfiles 0.2.500 → 0.2.502

package/docs/AI.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # AI Integrations (Opt-in)
 
 AI helpers are **off by default**. You choose if and when to turn them on.
@@ -25,7 +29,7 @@ Use the `dot` CLI to run AI tools with added context:
 
 ```bash
 # General usage
-dot cl|copilot|gemini|kiro|sgpt|ollama|opencode|aider|autohand|vibe|qwen|zai --pattern <name> "prompt"
+dot cl|codex|copilot|gemini|goose|kiro|sgpt|ollama|opencode|aider|autohand|vibe|qwen|zai --pattern <name> "prompt"
 
 # Quick aliases
 dcla "Optimize my zshrc"      # Claude + Architect
@@ -40,8 +44,10 @@ Supported bridge commands:
 | Command | Provider |
 |---------|----------|
 | `dot cl` | Claude Code |
+| `dot codex` | OpenAI Codex CLI |
 | `dot copilot` | GitHub Copilot CLI |
 | `dot gemini` | Gemini CLI |
+| `dot goose` | Goose (Block) |
 | `dot kiro` | Kiro CLI |
 | `dot sgpt` | Shell-GPT |
 | `dot ollama` | Ollama |
@@ -78,7 +84,7 @@ Related AI commands:
 
 These tools are not installed for you. Pick and install only the ones you want:
 
-- **Agents**: `claude`, `copilot`
+- **Agents**: `claude`, `codex`, `copilot`, `goose`
 - **Coding assistants**: `aider`, `opencode`
 - **General AI**: `gemini`, `sgpt`
 - **Local-first**: `ollama`

package/docs/CNAME

@@ -0,0 +1 @@
+doc.dotfiles.io

package/docs/COPYRIGHT

@@ -1,5 +1,5 @@
 /*
-* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.500) - <https://github.com/sebastienrousseau/dotfiles>
+* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.502) - <https://github.com/sebastienrousseau/dotfiles>
 * Made With ❤️ in London, United Kingdom
 * Designed by
 * Copyright (c) 2015-2026. All rights reserved.

package/docs/NAMING_CONVENTIONS.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Naming Conventions & Standardization Guide
 
 This document defines the naming conventions for all files in the dotfiles repository.
@@ -93,3 +98,5 @@ docs/             # Documentation and GitHub Pages source
   security/       # Security documentation
   operations/     # Ops and maintenance docs
 ```
+
+{% endraw %}

package/docs/README.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Documentation
 
 Start here. Then go deeper.

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

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # ADR-001: Multi-stage CI/CD Pipeline Design
 
 **Status**: Accepted
@@ -7,6 +12,7 @@
 ## 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
@@ -14,6 +20,7 @@ The dotfiles repository requires a CI/CD pipeline that:
 - 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
@@ -23,27 +30,33 @@ Traditional approaches run all checks on every commit, leading to:
 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
@@ -58,17 +71,20 @@ Use `dorny/paths-filter` to detect which file categories changed:
 ## 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
 
@@ -99,3 +115,4 @@ jobs:
 
 - [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,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-002: Shell Performance Optimization Strategy
 
 **Status**: Accepted
@@ -12,6 +16,7 @@ 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
@@ -84,6 +89,7 @@ zinit light zsh-users/zsh-autosuggestions
 ### Monitoring
 
 Benchmark script to track startup time:
+
 ```bash
 hyperfine --warmup 3 --runs 10 "zsh -i -c exit"
 ```
@@ -93,17 +99,20 @@ 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
 

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

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-003: Security-First Approach
 
 **Status**: Accepted
@@ -7,6 +11,7 @@
 ## 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
@@ -21,6 +26,7 @@ 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]]
@@ -29,6 +35,7 @@ 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"
@@ -36,6 +43,7 @@ chezmoi.age.identity = "~/.config/chezmoi/key.txt"
 ```
 
 **CI enforcement:**
+
 - Gitleaks runs on every PR
 - TruffleHog for verified secrets detection
 - Block merge if secrets detected
@@ -43,6 +51,7 @@ chezmoi.age.identity = "~/.config/chezmoi/key.txt"
 ### Layer 2: Input Validation
 
 **Path traversal prevention:**
+
 ```bash
 # Validate all user inputs
 if [[ ! "$template_lang" =~ ^[a-zA-Z0-9_-]+$ ]]; then
@@ -51,6 +60,7 @@ fi
 ```
 
 **Safe file operations:**
+
 ```bash
 # Use absolute paths, validate before operations
 local real_path
@@ -63,6 +73,7 @@ fi
 ### Layer 3: Opt-in System Modifications
 
 **Dangerous operations require explicit consent:**
+
 ```bash
 # Security scripts are opt-in
 if [ "${DOTFILES_SECURITY:-0}" != "1" ]; then
@@ -72,6 +83,7 @@ fi
 ```
 
 **Comprehensive logging:**
+
 ```bash
 # All system modifications logged
 log_security_change() {
@@ -82,6 +94,7 @@ log_security_change() {
 ### Layer 4: CI Security Scanning
 
 **Multi-tool approach:**
+
 - **Gitleaks**: Secrets in git history
 - **Shellcheck**: Shell script vulnerabilities
 - **Checkov**: Infrastructure misconfigurations
@@ -89,6 +102,7 @@ log_security_change() {
 - **CodeQL**: Static analysis for Python/JavaScript
 
 **Weekly deep scans:**
+
 ```yaml
 schedule:
   - cron: '0 2 * * 0'  # Weekly security audit
@@ -97,6 +111,7 @@ schedule:
 ### Layer 5: Minimal Privileges
 
 **Scripts request only needed permissions:**
+
 ```bash
 # Don't run as root unless necessary
 if [ "$(id -u)" = "0" ]; then
@@ -110,17 +125,20 @@ 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
 

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

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-004: Chezmoi + Custom CLI Wrapper Architecture
 
 **Status**: Accepted
@@ -7,12 +11,14 @@
 ## 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
@@ -45,18 +51,21 @@ Use **Chezmoi as the core engine** with a **custom `dot` CLI wrapper** that:
 ### 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/
@@ -72,6 +81,7 @@ scripts/dot/
 ```
 
 **4. Delegation pattern:**
+
 ```bash
 # Main dispatcher in dot CLI
 dispatch() {
@@ -94,6 +104,7 @@ dispatch() {
 ### 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)
@@ -102,6 +113,7 @@ Custom commands can:
 ## Consequences
 
 ### Positive
+
 - Leverage Chezmoi's battle-tested engine
 - User-friendly interface for common tasks
 - Easy to add domain-specific commands
@@ -109,11 +121,13 @@ Custom commands can:
 - 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

package/docs/adr/ADR-005-chezmoi-choice.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # ADR-005: Chezmoi as Dotfiles Manager
 
 **Status**: Accepted
@@ -7,6 +12,7 @@
 ## Context
 
 Managing dotfiles across multiple machines requires:
+
 - Version control for configuration files
 - Template support for machine-specific values
 - Cross-platform compatibility (macOS, Linux, WSL)
@@ -65,6 +71,7 @@ chezmoi apply
 ## Consequences
 
 ### Positive
+
 - Consistent configuration across all machines
 - Secure secrets management with age encryption
 - Easy to add new machines to the fleet
@@ -72,12 +79,14 @@ chezmoi apply
 - Built-in diff and dry-run for safe updates
 
 ### Negative
+
 - Learning curve for Go templates
 - Additional abstraction layer over raw Git
 - Requires chezmoi binary installation
 - Some features (scripts) require careful ordering
 
 ### Neutral
+
 - Configuration stored in `~/.local/share/chezmoi` by default
 - Custom wrapper CLI (`dot`) provides simpler interface
 - Regular `git` commands still work in source directory
@@ -87,3 +96,4 @@ chezmoi apply
 - [Chezmoi Documentation](https://www.chezmoi.io/)
 - [Chezmoi Quick Start](https://www.chezmoi.io/quick-start/)
 - [Comparison with Other Tools](https://www.chezmoi.io/comparison-table/)
+{% endraw %}

package/docs/adr/ADR-006-shell-selection.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-006: Zsh as Default Shell
 
 **Status**: Accepted
@@ -7,6 +11,7 @@
 ## Context
 
 Choosing a default shell impacts:
+
 - Developer productivity and workflow
 - Plugin ecosystem and extensibility
 - Cross-platform compatibility
@@ -45,6 +50,7 @@ Use **Zsh** as the default interactive shell with **Zinit** as the plugin manage
 | Antibody | ~300ms | Simple, fast |
 
 Zinit provides:
+
 - **Turbo Mode**: Deferred loading after prompt
 - **Ice Modifiers**: Fine-grained control over plugin loading
 - **Binary Installation**: Install completions and binaries
@@ -84,6 +90,7 @@ zinit light zdharma-continuum/fast-syntax-highlighting
 ## Consequences
 
 ### Positive
+
 - Fast, responsive shell experience
 - Rich plugin ecosystem (autosuggestions, syntax highlighting)
 - Powerful completion system
@@ -91,12 +98,14 @@ zinit light zdharma-continuum/fast-syntax-highlighting
 - Modern prompt with Starship
 
 ### Negative
+
 - Requires zsh installation on some Linux distros
 - Plugin manager adds complexity
 - Some bash-isms need adjustment
 - Turbo mode can cause brief visual delay
 
 ### Neutral
+
 - Users can still use bash for scripts
 - Configuration more complex than vanilla shell
 - Performance monitoring needed

package/docs/adr/ADR-007-multi-shell-parity.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-007: Multi-Shell Parity Strategy
 
 ## Status
@@ -12,9 +16,10 @@ Accepted
 
 The dotfiles distribution supports three shells: Zsh (default since macOS Catalina), Fish (modern interactive shell), and Nushell (structured data shell). The codebase has 98 alias files and 52+ functions written in POSIX/Bash. Without a parity strategy, each shell gets a fragmented subset of functionality.
 
-**Problem:** Fish had zero access to the alias/function library until v0.2.500 added bridge templates. Nushell had only 6 hardcoded aliases and no function access.
+**Problem:** Fish had zero access to the alias/function library until v0.2.501 added bridge templates. Nushell had only 6 hardcoded aliases and no function access.
 
 **Constraints:**
+
 - Nushell's `source` is parse-time evaluated (no dynamic sourcing)
 - Fish syntax differs significantly from POSIX (no `$()`, different `if`, no `[[`)
 - Maintaining N copies of every alias/function is unsustainable
@@ -31,6 +36,7 @@ Adopt a **hub-and-spoke bridge architecture**:
    - Functions: Chezmoi template-generated `def` wrappers delegating to bash (in `functions.nu.tmpl`)
 
 **Parity tiers:**
+
 - **Tier 1 (Full):** Zsh, Bash — all aliases, functions, lazy loading, cached eval
 - **Tier 2 (Bridged):** Fish — all simple aliases, all functions via wrappers, `_cached_eval` caching
 - **Tier 3 (Compatible):** Nushell — simple aliases (no complex bash syntax), all functions via bash delegation
@@ -38,16 +44,19 @@ Adopt a **hub-and-spoke bridge architecture**:
 ## Consequences
 
 ### Positive
+
 - Single source of truth for aliases and functions
 - Adding a new alias/function automatically propagates to all shells
 - Nushell users get access to 40+ functions that were previously unavailable
 - Fish users get mtime-aware caching via `_cached_eval`
 
 ### Negative
+
 - Complex bash aliases (pipes, conditionals) are skipped for Nushell
 - Function calls in Fish/Nushell incur bash subprocess overhead (~5ms per call)
 - Cache invalidation requires shell restart or manual cache clear
 
 ### Risks
+
 - Nushell's rapid development may break bridge syntax in future versions
 - Very large alias sets may slow Nushell startup during cache generation

package/docs/adr/ADR-008-alias-system-architecture.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-008: Alias System Architecture
 
 ## Status
@@ -13,6 +17,7 @@ Accepted
 The dotfiles manage 98 alias files across 30+ categories (git, docker, kubernetes, python, security, etc.). These need to load fast, support per-machine toggling, and work across Zsh, Bash, Fish, and Nushell.
 
 **Design questions:**
+
 1. How to organize alias files for maintainability?
 2. How to control which aliases load on which machines?
 3. How to balance startup speed with alias availability?
@@ -47,6 +52,7 @@ Three profiles control alias scope (set in `.chezmoidata.toml`):
 ### Bucket Toggles
 
 Per-category flags in `.chezmoidata.toml` under `[aliases.buckets]`:
+
 ```toml
 [aliases.buckets]
 system = true
@@ -62,6 +68,7 @@ svn = false    # disable on machines without SVN
 ### Function Groups (groups.json)
 
 Functions use a parallel system with `groups.json` as a registry:
+
 - Groups: api, curl, text, system, files, interactive, nav, security, misc
 - Lazy-loaded per group on first invocation
 - Stub functions replaced with real implementations on first call
@@ -69,17 +76,20 @@ Functions use a parallel system with `groups.json` as a registry:
 ## Consequences
 
 ### Positive
+
 - Adding aliases is self-service: create a file in the right category
 - Per-machine customization without forking
 - Lazy loading keeps startup under 200ms even with 98 alias files
 - `groups.json` enables automated bridge generation for Fish/Nushell
 
 ### Negative
+
 - Alias definitions wrap in functions (`set_default_aliases()`) for sourcing safety, adding complexity
 - Two-phase loading means some aliases aren't available until after first prompt
 - Profile/bucket system requires understanding .chezmoidata.toml
 
 ### Trade-offs
+
 - Chose file-per-category over monolithic alias file for maintainability
 - Chose runtime extraction for Fish/Nushell over maintaining parallel definitions
 - Chose lazy loading over compile-time bundling for flexibility