@sebastienrousseau/dotfiles 0.2.500 → 0.2.501

package/docs/operations/VERSION_SYNC.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Version Synchronization System
 
 The version synchronization system ensures that all version references across the repository remain consistent with the version specified in `package.json`.
@@ -5,7 +9,9 @@ The version synchronization system ensures that all version references across th
 ## Overview
 
 ### Problem Statement
+
 Large repositories often have version numbers scattered across multiple files:
+
 - README badges
 - Documentation headers
 - Feature version stamps
@@ -14,7 +20,9 @@ Large repositories often have version numbers scattered across multiple 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
@@ -26,17 +34,20 @@ This system provides automated version synchronization through:
 **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
@@ -47,6 +58,7 @@ This system provides automated version synchronization through:
 **Location**: `scripts/version-sync.sh`
 
 **Usage**:
+
 ```bash
 # Sync to current package.json version
 ./scripts/version-sync.sh
@@ -62,6 +74,7 @@ This system provides automated version synchronization through:
 ```
 
 **Options**:
+
 - `--dry-run` - Preview changes without applying
 - `--verify` - Check version consistency only
 - `--backup` / `--no-backup` - Control backup creation
@@ -72,15 +85,17 @@ This system provides automated version synchronization through:
 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)]
+[![Version](https://img.shields.io/badge/Version-v0.2.501-blue?style=for-the-badge)]
 ```
 
 #### Documentation Files
+
 ```markdown
-**Version**: v0.2.500
-**Dotfiles Version**: v0.2.500
-Version: v0.2.500
+**Version**: v0.2.501
+**Dotfiles Version**: v0.2.501
+Version: v0.2.501
 version 0.2.485
 ```
 
@@ -126,6 +141,7 @@ Version changes in `package.json` automatically trigger synchronization:
 ## Workflow Examples
 
 ### Scenario 1: Version Bump
+
 ```bash
 # Developer updates package.json version
 npm version patch
@@ -141,6 +157,7 @@ git push origin master
 ```
 
 ### Scenario 2: PR Review
+
 ```bash
 # PR with package.json changes
 # GitHub Actions automatically:
@@ -151,6 +168,7 @@ git push origin master
 ```
 
 ### Scenario 3: Manual Sync
+
 ```bash
 # Local development
 ./scripts/version-sync.sh --dry-run  # Preview changes
@@ -161,19 +179,25 @@ git push origin master
 ## 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
@@ -191,26 +215,33 @@ Files that are intentionally excluded:
 ### 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
@@ -220,6 +251,7 @@ git checkout HEAD~1 -- README.md
 ```
 
 #### Force Resync
+
 ```bash
 ./scripts/version-sync.sh --force
 ```
@@ -227,19 +259,23 @@ git checkout HEAD~1 -- README.md
 ## 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
@@ -247,6 +283,7 @@ The GitHub Actions workflow provides metrics:
 ## Security Considerations
 
 ### Token Permissions
+
 ```yaml
 permissions:
   contents: write      # Required for commits
@@ -254,11 +291,13 @@ permissions:
 ```
 
 ### 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
@@ -266,16 +305,19 @@ permissions:
 ## 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)
@@ -283,6 +325,7 @@ permissions:
 ## 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
@@ -290,6 +333,7 @@ permissions:
 5. **Integration Testing** - End-to-end workflow tests
 
 ### Extension Points
+
 - Custom pattern definitions
 - File-specific update rules
 - Pre/post-sync hooks
@@ -298,12 +342,14 @@ permissions:
 ## 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` |
@@ -313,6 +359,7 @@ DEBUG=1 ./scripts/version-sync.sh --dry-run
 | Changes not committed | Check branch protection rules |
 
 ### Log Analysis
+
 ```bash
 # View GitHub Actions logs
 gh run list --workflow=sync-versions.yml
@@ -322,6 +369,7 @@ gh run view <run-id> --log
 ## Contributing
 
 ### Testing Changes
+
 ```bash
 # Test local changes
 ./scripts/version-sync.sh --dry-run
@@ -331,6 +379,7 @@ 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
@@ -339,6 +388,6 @@ gh workflow run sync-versions.yml --ref feature-branch
 ---
 
 **Last Updated**: 2026-02-15
-**Version**: v0.2.500
+**Version**: v0.2.501
 **Maintainer**: Principal Automation Engineer
 **Status**: Production Ready ✅

package/docs/reference/ALIASES.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Aliases
 
 Shell aliases provided by the dotfiles, organized by category in `~/.dotfiles/.chezmoitemplates/aliases/`.
@@ -107,11 +111,13 @@ Shell aliases provided by the dotfiles, organized by category in `~/.dotfiles/.c
 ## Adding custom aliases
 
 1. Create a new file in the appropriate category:
+
    ```bash
    vim ~/.dotfiles/.chezmoitemplates/aliases/mycategory/mycategory.aliases.sh
    ```
 
 2. Define your aliases:
+
    ```bash
    # shellcheck shell=bash
    # My Custom Aliases
@@ -119,6 +125,7 @@ Shell aliases provided by the dotfiles, organized by category in `~/.dotfiles/.c
    ```
 
 3. Apply changes:
+
    ```bash
    chezmoi apply
    ```

package/docs/reference/ALIASES_CHEATSHEET.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Alias Cheatsheet
 
 Auto-generated from the alias manifest.
@@ -10,7 +14,7 @@ Auto-generated from the alias manifest.
 | `q` | `quit` |
 | `e` | `${EDITOR:-nano}` |
 | `h` | `history` |
-| `_` | `sudo ` |
+| `_` | `sudo` |
 | `i` | `epoch` |
 | `l` | `dot_ls` |
 | `ll` | `dot_ll` |

package/docs/reference/ALIASES_DEPRECATIONS.md

@@ -1,9 +1,13 @@
+---
+render_with_liquid: false
+---
+
 # 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 |
+| `dlogsf` | `dklf` | `v0.2.501` | Removed duplicate logs-follow alias |
 
 Use `dot aliases why <alias>` to check deprecation status from the CLI.

package/docs/reference/FEATURES.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # 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`.

package/docs/reference/FONTS.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Font configuration
 
 How fonts are set up, rendered, and installed in these dotfiles.

package/docs/reference/PROFILES.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Profiles and Machine Setup
 
 ## Profile System

package/docs/reference/SCREENSHOTS.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Screenshots Gallery
 
 Here's how the dotfiles look across different themes and configurations.

package/docs/reference/SCRIPTS.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Script Catalog
 
 Exhaustive catalog of user-facing executables installed from `dot_local/bin/`.

package/docs/reference/SUPPORT_MATRIX.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Support Matrix
 
 Tested platform and tool combinations for the dotfiles distribution.
@@ -31,10 +35,12 @@ Tested platform and tool combinations for the dotfiles distribution.
 | Terminal | Status | Notes |
 |----------|--------|-------|
 | Ghostty | Supported | Primary, custom config in `dot_config/ghostty/` |
-| iTerm2 | Supported | macOS, profile config included |
-| Alacritty | Supported | Config in `dot_config/alacritty/` |
-| Kitty | Supported | Config in `dot_config/kitty/` |
-| WezTerm | Supported | Config in `dot_config/wezterm/` |
+| iTerm2 | Supported | macOS only; auto-installed Dynamic Profile via `run_onchange_22-iterm2-profile.sh.tmpl` (pick "dotfiles" profile in iTerm2) |
+| Alacritty | Supported | Theme-driven, config in `dot_config/alacritty/` |
+| Kitty | Supported | Theme-driven, config in `dot_config/kitty/` |
+| WezTerm | Supported | Theme-driven, config in `dot_config/wezterm/` |
+| Foot | Supported | Linux/Wayland, gated by `features.foot`, config in `dot_config/foot/` |
+| Warp | Supported | Theme-driven, deploys to `~/.warp/themes/dotfiles.yaml`; pick "dotfiles" in Warp Settings → Appearance → Themes |
 | Windows Terminal | Supported | WSL2 profile |
 | tmux | Supported | Config in `dot_config/tmux/` |
 

package/docs/reference/THEMES.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Themes
 
 Themes are auto-generated from wallpapers. K-Means clustering in CIELAB color space extracts dominant colors. Every theme is WCAG AAA compliant.

package/docs/reference/TOOLS.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Tools
 
 Integrated tools organized by role in the workflow.

package/docs/reference/UTILS.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Utilities
 
 Aliases, functions, and the `dot` CLI provide day-to-day tooling across macOS, Linux, and WSL.
@@ -34,31 +38,31 @@ The `dot` command is the main interface for managing dotfiles. Run `dot version`
 
 | Command | Description |
 |---------|-------------|
-| `dot doctor` | Run system health checks (`--score|-s`, `--heal|-H`) |
-| `dot health` | Run the health dashboard (`--verbose|-v`, `--json|-j`, `--fix|-f`, `--force|-F`) |
-| `dot heal` | Auto-repair missing tools, chezmoi drift, broken symlinks, and critical files (`--dry-run|-n`, `--force|-f`) |
+| `dot doctor` | Run system health checks (`--score/-s`,`--heal/-H`) |
+| `dot health` | Run the health dashboard (`--verbose/-v`,`--json/-j`,`--fix/-f`,`--force/-F`) |
+| `dot heal` | Auto-repair missing tools, chezmoi drift, broken symlinks, and critical files (`--dry-run/-n`,`--force/-f`) |
 | `dot smoke-test` | Verify toolchains (Rust, Go, AI CLIs) |
-| `dot verify` | Run security and integrity verification (`--security|-s`) |
+| `dot verify` | Run security and integrity verification (`--security/-s`) |
 | `dot chaos` | Simulate config corruption to test self-healing |
 | `dot rollback` | Roll back dotfiles to the previous known-good state |
 | `dot drift` | Detailed configuration drift dashboard |
-| `dot benchmark` | Measure shell startup time (`--detailed|-d`, `--profile|-p`, `--compare|-c`, `--waterfall|-w`) |
-| `dot perf` | Show performance mode + quick timing (`--json|-j`, `--profile|-p`, `--runs|-r`, `--target|-t`) |
+| `dot benchmark` | Measure shell startup time (`--detailed/-d`,`--profile/-p`,`--compare/-c`,`--waterfall/-w`) |
+| `dot perf` | Show performance mode + quick timing (`--json/-j`,`--profile/-p`,`--runs/-r`,`--target/-t`) |
 | `dot score` | Show the high-level system health and security scorecard |
 | `dot metrics` | Show recent observability metrics |
 | `dot load-bench` | Measure heavy-layer readiness |
-| `dot mcp` | Validate MCP policy and registry (`--strict|-s`, `--json|-j`) |
-| `dot attest` | Export workstation evidence (`--json|-j`, `--write|-w`, `--fleet-store|-F`) |
+| `dot mcp` | Validate MCP policy and registry (`--strict/-s`,`--json/-j`) |
+| `dot attest` | Export workstation evidence (`--json/-j`,`--write/-w`,`--fleet-store/-F`) |
 | `dot history` | Analyse shell history |
-| `dot security-score` | Score workstation security (`--verbose|-v`, `--quiet|-q`, `--json|-j`) |
-| `dot snapshot` | Capture workstation state (`--baseline|-b`, `--force|-f`) |
+| `dot security-score` | Score workstation security (`--verbose/-v`,`--quiet/-q`,`--json/-j`) |
+| `dot snapshot` | Capture workstation state (`--baseline/-b`,`--force/-f`) |
 | `dot ai` | Show categorized AI CLI status and launch an installed provider |
 | `dot ai-setup` | Bootstrap supported AI CLIs interactively |
 | `dot ai-query` | Run context-aware AI queries over the repo |
 | `dot mode` | Show or switch the active agent profile |
 | `dot agent` | Inspect agent metadata, logs, checkpoints, and conformance |
 | `dot agent checkpoint` | Save, list, show, and replay bounded agent checkpoints |
-| `dot agent conformance` | Validate A2A discovery and agent card conformance (`--strict|-s`, `--json|-j`) |
+| `dot agent conformance` | Validate A2A discovery and agent card conformance (`--strict/-s`,`--json/-j`) |
 
 ### Tools
 
@@ -74,7 +78,7 @@ The `dot` command is the main interface for managing dotfiles. Run `dot version`
 | `dot learn` | Start the guided onboarding tour |
 | `dot docs` | Show the main repository documentation |
 | `dot log-rotate` | Rotate `~/.local/share/dotfiles.log` |
-| `dot lint` | Lint shell scripts (`--check|-c`, `--fix|-f`) |
+| `dot lint` | Lint shell scripts (`--check/-c`,`--fix/-f`) |
 
 ## Universal Scripts
 

package/docs/security/AI_ACT_COMPLIANCE.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # EU AI Act Compliance Assessment
 
 This document maps the dotfiles project against the EU Artificial Intelligence Act (Regulation (EU) 2024/1689) to confirm compliance posture and applicable obligations.

package/docs/security/AUDIT_BYPASS.md

@@ -0,0 +1,103 @@
+---
+render_with_liquid: false
+---
+
+# Pre-Push Audit Bypass
+
+This page documents when the pre-push reliability audit can be bypassed,
+how to do it, and why the answer is "almost never on `master`."
+
+## Background
+
+`scripts/git-hooks/pre-push` runs two checks on every push:
+
+1. **Signed-commit verification** — every commit being pushed must have
+   a valid GPG/SSH signature. No bypass is available; an unsigned
+   commit is refused unconditionally.
+
+2. **Reliability audit** — `scripts/qa/reliability-audit.sh --quick`
+   runs a fast subset of the test suite + lint checks. This is the
+   step that can be bypassed.
+
+Before issue #871 the audit was opt-out: `DOTFILES_SKIP_PRE_PUSH_AUDIT=1`
+in your shell rc would silently skip every push's audit. Bypass was
+invisible, persistent, and one keystroke away. That's the wrong default.
+
+## The new policy
+
+Effective with #871 and the corresponding commit on this branch:
+
+- The audit **always runs by default**. Missing env var → audit runs.
+- Bypass requires `DOTFILES_ALLOW_UNSKIPPED_PUSH=1` set inline for the
+  one push you want to bypass (not exported in your shell rc).
+- The legacy `DOTFILES_SKIP_PRE_PUSH_AUDIT=1` is **rejected** with a
+  migration message; the hook exits non-zero if it sees the old var.
+- Every bypass is appended to
+  `${XDG_STATE_HOME:-~/.local/state}/dotfiles/audit-bypass.log` with
+  timestamp, branch, remote, and reason.
+- `dot doctor` reports the count of bypasses in the last 7 days.
+
+The new variable name is deliberately awkward
+(`DOTFILES_ALLOW_UNSKIPPED_PUSH`) — it should not feel like a routine
+flag. Setting it should require a moment's thought.
+
+## How to bypass for a single push
+
+```bash
+DOTFILES_ALLOW_UNSKIPPED_PUSH=1 \
+DOTFILES_BYPASS_REASON='hotfix: CI is wedged on flake' \
+  git push origin hotfix/my-branch
+```
+
+The reason string is optional but encouraged. It lands in the audit log
+so `dot doctor` and any future review can answer "why was this
+bypassed?" without git archaeology.
+
+## When bypass is legitimate
+
+Short list — anything outside this is suspicious:
+
+- **Hotfix push to a non-master branch** when CI infrastructure itself
+  is the audit blocker (e.g., the audit pre-flight depends on a remote
+  service that's down). The fix should land *before* the
+  infrastructure recovers; bypass is the bridge.
+- **Force-push of a tag rewind** that doesn't introduce new commits
+  (rare).
+
+When bypass is **not** legitimate:
+
+- Routine `master` pushes. The whole point of the audit is to guard
+  the protected branch.
+- Pushes whose audit failure is "annoying" — the right move is to fix
+  the failure, not skip the check.
+- CI environments. CI should run the audit explicitly, never bypass
+  it; if a CI job pushes, the env var must remain unset there.
+
+## Verifying current state
+
+```bash
+dot doctor   # surfaces recent bypasses
+cat ${XDG_STATE_HOME:-~/.local/state}/dotfiles/audit-bypass.log
+```
+
+Each line of the log is tab-separated:
+`ISO8601-timestamp \t branch=... \t remote=... \t reason=...`.
+
+## Disabling bypass entirely
+
+If your machine should *never* bypass (e.g., a release runner), unset
+the env var in your shell rc and add a guard to your `.zshenv` or
+equivalent:
+
+```bash
+unset DOTFILES_ALLOW_UNSKIPPED_PUSH
+```
+
+There's no way to permanently grant bypass — that's intentional.
+
+## References
+
+- `scripts/git-hooks/pre-push` — the hook itself
+- `scripts/diagnostics/doctor.sh` — the "Pre-Push Audit Bypass" section
+- `tests/unit/security/test_pre_push_bypass.sh` — regression test
+- Issue #871

package/docs/security/AUTOMATION_SECRETS.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Automation Secrets
 
 ## Required secrets