@sebastienrousseau/dotfiles 0.2.500 → 0.2.501

package/docs/guides/WSL2_NIX_TROUBLESHOOTING.md

@@ -1,6 +1,11 @@
+---
+render_with_liquid: false
+---
+
 # WSL2 & Nix Integration Troubleshooting Guide
 
 ### Metadata
+
 - **Type:** How-To Guide / Reference
 - **Audience:** Intermediate / Advanced
 - **Prerequisites:** Basic familiarity with command line, WSL2, and Nix package manager
@@ -25,6 +30,7 @@ A comprehensive troubleshooting guide for WSL2 edge cases, Nix integration issue
 ### Filesystem Issues
 
 #### Problem: Symlinks fail to work between Windows and WSL2
+
 ```bash
 # Check if symlinks are enabled
 ls -la ~/.dotfiles/
@@ -34,13 +40,16 @@ ls -la ~/.dotfiles/
 **Root Cause:** Windows filesystem doesn't support Unix symlinks by default.
 
 **Solutions:**
+
 1. **Enable Developer Mode** (Windows 10/11):
+
    ```powershell
    # Run in PowerShell as Administrator
    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
    ```
 
 2. **Use WSL2 native filesystem**:
+
    ```bash
    # Move dotfiles to WSL2 filesystem
    cd ~
@@ -48,12 +57,14 @@ ls -la ~/.dotfiles/
    ```
 
 3. **Configure Git for WSL2**:
+
    ```bash
    git config --global core.symlinks true
    git config --global core.autocrlf false
    ```
 
 #### Problem: Slow filesystem performance on Windows drives
+
 ```bash
 # Test filesystem performance
 time ls -la /mnt/c/Users/
@@ -63,12 +74,14 @@ time ls -la ~/
 **Solution:** Always work within WSL2 filesystem (`~/`) for performance-critical operations.
 
 #### Problem: Permission denied errors on mounted Windows drives
+
 ```bash
 # Check mount options
 mount | grep drvfs
 ```
 
 **Solution:** Remount with proper permissions:
+
 ```bash
 # Create /etc/wsl.conf
 sudo tee /etc/wsl.conf > /dev/null <<EOF
@@ -86,6 +99,7 @@ wsl --shutdown
 ### Networking Issues
 
 #### Problem: DNS resolution fails in WSL2
+
 ```bash
 # Test DNS resolution
 nslookup github.com
@@ -93,15 +107,19 @@ ping github.com
 ```
 
 **Solutions:**
+
 1. **Reset WSL2 DNS**:
+
    ```bash
    sudo rm /etc/resolv.conf
    sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
    ```
 
 2. **Configure permanent DNS**:
+
    ```bash
    sudo tee /etc/wsl.conf > /dev/null <<EOF
+
 [network]
 generateResolvConf = false
 EOF
@@ -110,6 +128,7 @@ EOF
 nameserver 1.1.1.1
 nameserver 8.8.8.8
 EOF
+
    ```
 
 #### Problem: Port forwarding doesn't work
@@ -119,6 +138,7 @@ netstat -tulpn | grep :3000
 ```
 
 **Solution:** Use Windows port proxy:
+
 ```powershell
 # Run in PowerShell as Administrator
 netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=172.x.x.x
@@ -127,6 +147,7 @@ netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 conne
 ### Memory and Resource Issues
 
 #### Problem: WSL2 consumes excessive memory
+
 ```bash
 # Check WSL2 memory usage
 cat /proc/meminfo | grep MemTotal
@@ -134,6 +155,7 @@ free -h
 ```
 
 **Solution:** Limit WSL2 memory usage:
+
 ```ini
 # Create %UserProfile%\.wslconfig
 [wsl2]
@@ -143,7 +165,9 @@ swap=2GB
 ```
 
 #### Problem: WSL2 doesn't release memory back to Windows
+
 **Solution:** Compact WSL2 virtual disk:
+
 ```powershell
 # Run in PowerShell as Administrator
 wsl --shutdown
@@ -162,6 +186,7 @@ diskpart
 ### Installation Problems
 
 #### Problem: Nix installation fails on WSL2
+
 ```bash
 # Check if installation attempted
 ls -la /nix/
@@ -169,23 +194,29 @@ which nix
 ```
 
 **Solutions:**
+
 1. **Use deterministic installer**:
+
    ```bash
    curl -L https://nixos.org/nix/install | sh -s -- --daemon
    ```
 
 2. **Fix permissions after installation**:
+
    ```bash
    sudo chown -R $(whoami) /nix/var/nix/profiles/per-user/$(whoami)/
    sudo chmod -R 755 /nix/var/nix/profiles/per-user/$(whoami)/
    ```
 
 3. **Enable systemd for Nix daemon** (WSL2 Ubuntu 22.04+):
+
    ```bash
    sudo tee /etc/wsl.conf > /dev/null <<EOF
+
 [boot]
 systemd=true
 EOF
+
    ```
 
 #### Problem: Nix flakes not recognized
@@ -195,6 +226,7 @@ nix flake --help
 ```
 
 **Solution:** Enable experimental features:
+
 ```bash
 mkdir -p ~/.config/nix/
 tee ~/.config/nix/nix.conf > /dev/null <<EOF
@@ -210,18 +242,22 @@ EOF
 ```
 
 #### Problem: SSL certificate errors during Nix operations
+
 ```bash
 # Test Nix store access
 nix ping-store
 ```
 
 **Solutions:**
+
 1. **Update CA certificates**:
+
    ```bash
    sudo apt update && sudo apt install ca-certificates
    ```
 
 2. **Configure Nix with custom CA bundle**:
+
    ```bash
    export NIX_SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
    echo 'export NIX_SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt' >> ~/.bashrc
@@ -230,6 +266,7 @@ nix ping-store
 ### Flake and Profile Issues
 
 #### Problem: Flake lock file conflicts
+
 ```bash
 # Check flake lock status
 cd ~/.dotfiles/nix/
@@ -237,6 +274,7 @@ nix flake check --impure
 ```
 
 **Solution:** Update and rebuild lock file:
+
 ```bash
 cd ~/.dotfiles/nix/
 rm flake.lock
@@ -245,6 +283,7 @@ nix flake check
 ```
 
 #### Problem: Nix profile conflicts with system packages
+
 ```bash
 # List Nix profiles
 nix profile list
@@ -253,29 +292,35 @@ which -a git
 ```
 
 **Solutions:**
+
 1. **Remove conflicting profiles**:
+
    ```bash
    nix profile remove <profile-number>
    ```
 
 2. **Use priority settings**:
+
    ```bash
    nix profile install nixpkgs#git --priority 10
    ```
 
 3. **Create isolated development environments**:
+
    ```bash
    cd ~/.dotfiles/nix/
    nix develop
    ```
 
 #### Problem: Nix store corruption
+
 ```bash
 # Check store integrity
 nix-store --verify --check-contents
 ```
 
 **Solution:** Repair corrupted store:
+
 ```bash
 # Stop Nix daemon
 sudo systemctl stop nix-daemon
@@ -290,12 +335,14 @@ sudo systemctl start nix-daemon
 ### Build and Cache Issues
 
 #### Problem: Binary cache not working
+
 ```bash
 # Test cache connectivity
 nix ping-store --store https://cache.nixos.org
 ```
 
 **Solution:** Configure trusted substituters:
+
 ```bash
 sudo tee -a /etc/nix/nix.conf > /dev/null <<EOF
 substituters = https://cache.nixos.org/ https://nix-community.cachix.org
@@ -304,6 +351,7 @@ EOF
 ```
 
 #### Problem: Out of disk space during build
+
 ```bash
 # Check Nix store size
 du -sh /nix/store/
@@ -311,6 +359,7 @@ df -h /nix/
 ```
 
 **Solution:** Clean up Nix store:
+
 ```bash
 # Remove unused packages
 nix-collect-garbage
@@ -329,6 +378,7 @@ nix-store --optimise
 ### Complete System Recovery
 
 #### Scenario: Dotfiles installation completely broken
+
 ```bash
 # 1. Backup current state
 cp ~/.zshrc ~/.zshrc.backup.$(date +%s)
@@ -348,6 +398,7 @@ curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/ins
 ```
 
 #### Scenario: WSL2 completely broken
+
 ```powershell
 # From Windows PowerShell as Administrator
 
@@ -367,6 +418,7 @@ wsl -d Ubuntu -u root -- curl -fsSL https://raw.githubusercontent.com/sebastienr
 ### Partial Recovery
 
 #### Fix broken Nix installation
+
 ```bash
 # 1. Remove broken Nix
 sudo rm -rf /nix/
@@ -387,6 +439,7 @@ which nix
 ```
 
 #### Fix broken shell configuration
+
 ```bash
 # 1. Use emergency shell config
 cat > ~/.zshrc.emergency <<'EOF'
@@ -414,6 +467,7 @@ chezmoi apply
 ### Data Recovery
 
 #### Recover encrypted secrets
+
 ```bash
 # 1. Check if key file exists
 ls -la ~/.config/chezmoi/key.txt
@@ -430,6 +484,7 @@ chezmoi execute-template --init --force
 ```
 
 #### Recover Git configuration
+
 ```bash
 # 1. Check current git config
 git config --list --show-origin
@@ -453,6 +508,7 @@ git config --get core.editor
 ### WSL2 Performance Tuning
 
 #### Optimize filesystem performance
+
 ```bash
 # 1. Move frequently accessed files to WSL2 filesystem
 mkdir -p ~/workspace
@@ -469,6 +525,7 @@ export EDITOR="nvim"
 ```
 
 #### Reduce memory usage
+
 ```bash
 # 1. Limit shell history
 echo 'HISTSIZE=1000' >> ~/.zshrc
@@ -485,6 +542,7 @@ echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
 ### Nix Performance Tuning
 
 #### Optimize Nix builds
+
 ```bash
 # Configure build settings
 sudo tee -a /etc/nix/nix.conf > /dev/null <<EOF
@@ -497,6 +555,7 @@ EOF
 ```
 
 #### Enable build caching
+
 ```bash
 # Install and configure cachix
 nix profile install nixpkgs#cachix
@@ -513,6 +572,7 @@ echo 'eval "$(cachix completion bash)"' >> ~/.bashrc
 ### Moving from macOS to WSL2
 
 #### Environment differences checklist
+
 ```bash
 # 1. Check path differences
 echo $PATH | tr ':' '\n' | sort
@@ -528,6 +588,7 @@ which nix 2>/dev/null && echo "Nix found"
 ```
 
 #### Migration procedure
+
 ```bash
 # 1. Export current configuration
 cd ~/.dotfiles
@@ -551,6 +612,7 @@ chezmoi apply
 ### Moving from Linux to WSL2
 
 #### Handle systemd differences
+
 ```bash
 # Check systemd status
 systemctl is-system-running 2>/dev/null || echo "systemd not available"
@@ -560,6 +622,7 @@ sudo service ssh start  # Instead of systemctl start ssh
 ```
 
 #### Network configuration migration
+
 ```bash
 # 1. Export network settings from source system
 ip route show > network-config.txt
@@ -576,6 +639,7 @@ cat /etc/resolv.conf >> network-config.txt
 ### Emergency Shell Access
 
 #### If shell is completely broken
+
 ```bash
 # 1. Access via different shell
 /bin/bash --noprofile --norc
@@ -591,6 +655,7 @@ alias ll='ls -la'
 ```
 
 #### If WSL2 won't start
+
 ```powershell
 # From Windows PowerShell as Administrator
 
@@ -610,6 +675,7 @@ net start LxssManager
 ### Emergency Contacts and Resources
 
 #### Diagnostic commands for support requests
+
 ```bash
 # System information
 cat /etc/os-release
@@ -652,6 +718,7 @@ echo "Diagnostic report saved to ~/diagnostic-report.txt"
 ```
 
 #### Support channels
+
 - GitHub Issues: [Repository Issues](https://github.com/sebastienrousseau/dotfiles/issues)
 - WSL2 Documentation: [Microsoft WSL Docs](https://docs.microsoft.com/en-us/windows/wsl/)
 - Nix Documentation: [Nix Manual](https://nixos.org/manual/nix/stable/)
@@ -662,6 +729,7 @@ echo "Diagnostic report saved to ~/diagnostic-report.txt"
 ## Quick Reference
 
 ### Essential Commands
+
 ```bash
 # System status
 dot doctor                    # Run dotfiles health check
@@ -681,6 +749,7 @@ export PATH=/usr/bin:/bin    # Minimal PATH
 ```
 
 ### Recovery Commands
+
 ```bash
 # Nuclear options (use with caution)
 rm -rf ~/.local/share/chezmoi/     # Reset chezmoi
@@ -720,4 +789,4 @@ time ls ~/.dotfiles >/dev/null
 free -m 2>/dev/null || vm_stat | head -5
 ```
 
-Run this checklist and include the output when requesting support.
+Run this checklist and include the output when requesting support.

package/docs/index.md

@@ -1,9 +1,13 @@
+---
+render_with_liquid: false
+---
+
 # .dotfiles
 
 Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL.
 
 [![Build](https://img.shields.io/github/actions/workflow/status/sebastienrousseau/dotfiles/ci.yml?style=for-the-badge&logo=github)](https://github.com/sebastienrousseau/dotfiles/actions)
-[![Version](https://img.shields.io/badge/Version-v0.2.500-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.500)
+[![Version](https://img.shields.io/badge/Version-v0.2.501-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.501)
 [![Downloads](https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases)
 
 This site is published from the `docs/` directory on `master` and tracks the current workstation baseline, operational guidance, and security material for the repository.
@@ -34,6 +38,6 @@ This site is published from the `docs/` directory on `master` and tracks the cur
 
 ## Current Release
 
-- Current tagged release: [`v0.2.500`](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.500)
+- Current tagged release: [`v0.2.501`](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.501)
 - Latest release feed: [GitHub releases](https://github.com/sebastienrousseau/dotfiles/releases/latest)
 - Source repository: [sebastienrousseau/dotfiles](https://github.com/sebastienrousseau/dotfiles)

package/docs/interop/A2A.md

@@ -1,12 +1,18 @@
+---
+render_with_liquid: false
+---
+
 # Agent Interop
 
 The repository now ships an agent card and an A2A-ready discovery document.
 
 Artifacts:
+
 - [agent-card.json](/home/seb/.dotfiles/dot_config/dotfiles/agent-card.json)
 - [agent.json](/home/seb/.dotfiles/.well-known/agent.json)
 
 Core properties:
+
 - bounded profiles: `ask`, `plan`, `apply`, `audit`
 - MCP-governed execution
 - workstation attestation export
@@ -15,6 +21,7 @@ Core properties:
 - fleet attestation export
 
 Tracked governance artifacts:
+
 - policy bundles
 - prompt registry
 - model registry

package/docs/interop/POWERSHELL.md

@@ -0,0 +1,102 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
+# PowerShell Parity
+
+This page documents how PowerShell 7.5+ support is exercised in CI
+and what specifically is verified. Closes the docs slice of
+[#860](https://github.com/sebastienrousseau/dotfiles/issues/860).
+
+## What ships
+
+| File | Role |
+|---|---|
+| [`dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl`](../../dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl) | The dotfiles PowerShell profile. Deployed to `$PROFILE` (resolves to `~/.config/powershell/Microsoft.PowerShell_profile.ps1` on Linux/macOS; `Documents\PowerShell\Microsoft.PowerShell_profile.ps1` on Windows). |
+| [`scripts/qa/powershell-contract.ps1`](../../scripts/qa/powershell-contract.ps1) | The runtime contract. Renders the template, dot-sources it, asserts required function shims exist, runs PSScriptAnalyzer. |
+| [`tests/unit/install/test_powershell_profile_syntax.sh`](../../tests/unit/install/test_powershell_profile_syntax.sh) | Static-syntax test runnable on Linux/macOS via `pwsh` when present; falls back to brace-balance + textual invariants when not. |
+
+## What's verified
+
+### On every Linux/macOS PR (`tests/unit/install/...`)
+
+- Profile file exists at the expected path.
+- Defines the `dot` function shim so PowerShell users invoke the
+  same CLI as Unix shells.
+- Sets `XDG_CONFIG_HOME` (matches Unix XDG conventions for
+  `~/.config/powershell` discoverability).
+- Brace count balances (`{` vs `}`).
+- If `pwsh` is installed locally, parses the rendered template via
+  `System.Management.Automation.Language.Parser` and fails on any
+  parse error.
+
+### On `windows-latest` runner via reliability-gate.yml
+
+The `powershell-contract` job runs `scripts/qa/powershell-contract.ps1`
+which does:
+
+1. **Renders the template** via `chezmoi execute-template` so any
+   chezmoi data references (e.g. `{{ .dotfiles_version }}`) resolve
+   to real values before parsing.
+2. **Dot-sources** the rendered profile and asserts no exception is
+   thrown during load.
+3. **Asserts the required function shims** are defined after load:
+   `dot`, `d`, `ll`, `la`, `cat`.
+4. **Runs PSScriptAnalyzer** at `Error` severity. Warnings surface
+   but don't fail the gate (tightenable later).
+
+Exit non-zero on any failure. The job is in the `reliability-summary`
+required-checks list so a broken PowerShell profile blocks merge.
+
+## Running locally
+
+### On Linux/macOS
+
+```bash
+# Static test — runs in any context.
+bash tests/unit/install/test_powershell_profile_syntax.sh
+
+# Full contract — needs pwsh + chezmoi installed.
+brew install --cask powershell   # or apt / package manager equivalent
+pwsh ./scripts/qa/powershell-contract.ps1
+```
+
+### On Windows
+
+```powershell
+.\scripts\qa\powershell-contract.ps1
+```
+
+## Known limitations
+
+- The contract doesn't currently exercise PowerShell-specific runtime
+  semantics (e.g. PSDrive providers, custom completion). Those are a
+  follow-up.
+- Function shims are smoke-tested by name only — we check that
+  `Get-Command dot` resolves to a function, not that it actually
+  invokes the right binary. A richer integration test that creates a
+  fake `dot` binary and confirms the shim invokes it correctly is a
+  future hardening step.
+- macOS is not in the matrix because `pwsh` isn't pre-installed on
+  GitHub macOS runners. The Linux/macOS static test runs on every PR
+  via the existing test suite; full pwsh validation is Windows-only
+  to keep the matrix small.
+
+## When to update this page
+
+- The PowerShell profile gains a new function → add it to the
+  `RequiredFunctions` array in `powershell-contract.ps1` AND to the
+  list above.
+- A static-test invariant is added → document it in the "What's
+  verified on every PR" list.
+- The PSScriptAnalyzer severity is tightened from `Error` to
+  `Warning` → update the relevant bullet here.
+
+## References
+
+- [PowerShell 7 docs](https://learn.microsoft.com/en-us/powershell/scripting/overview)
+- [PSScriptAnalyzer rule reference](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/README.md)
+- `.github/workflows/reliability-gate.yml` — Windows job definition.
+- Issue [#860](https://github.com/sebastienrousseau/dotfiles/issues/860).
+{% endraw %}

package/docs/manual/00-introduction.md

@@ -1,6 +1,10 @@
+---
+render_with_liquid: false
+---
+
 # Introduction
 
-This manual describes `.dotfiles` v0.2.500 — a trusted agent workstation baseline for macOS, Linux, and WSL.
+This manual describes `.dotfiles` v0.2.501 — a trusted agent workstation baseline for macOS, Linux, and WSL.
 
 The repository is more than a personal dotfiles collection. It ships as workstation infrastructure: signed, attested, multi-platform, AI-aware, and self-healing. Chezmoi handles templating and platform differences. The `dot` CLI sits on top and coordinates lifecycle operations.
 

package/docs/manual/01-concepts/01-architecture.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Architecture
 
 `.dotfiles` is composed of four loosely coupled subsystems, coordinated by a single command-line interface.

package/docs/manual/01-concepts/02-trust-model.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Trust Model
 
 The trust model combines cryptographic signing, local-first secrets, policy-gated agent operations, and machine-verifiable attestation.
@@ -6,7 +10,7 @@ The trust model combines cryptographic signing, local-first secrets, policy-gate
 
 | Threat | Mitigation |
 |:---|:---|
-| Unauthorized code execution on the workstation | Signed commits, shellcheck gates, no `curl | sh` in install path |
+| Unauthorized code execution on the workstation | Signed commits, shellcheck gates, no `curl \| sh` in install path |
 | Secret leakage into Git history | Age/SOPS encryption, gitleaks in CI, `detect-secrets` baseline |
 | Tampered upstream tool | SHA256-pinned chezmoi installer, SBOM + Grype CVE scan |
 | Malicious agent behavior | MCP policy enforcement, agent profile allowlists, attestation logs |
@@ -94,7 +98,7 @@ Violations are logged to `~/.local/state/dotfiles/mcp-violations.log` and report
 
 ```json
 {
-  "version": "0.2.500",
+  "version": "0.2.501",
   "timestamp": "2026-04-16T09:00:00Z",
   "host": {
     "hostname_sha256": "...",

package/docs/manual/01-concepts/03-theme-engine.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # The Theme Engine
 
 `.dotfiles` generates terminal color palettes directly from wallpaper images. There are no hand-crafted themes — dominant colors are extracted via K-Means clustering in CIELAB color space, mapped to ANSI slots, and enforced to WCAG AAA contrast.

package/docs/manual/01-concepts/04-fleet.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Fleet Architecture
 
 A "fleet" is two or more workstations sharing a single `.dotfiles` source repository. The fleet model handles per-host customization, drift detection, and cross-host trust propagation.
@@ -67,7 +72,7 @@ Drift is normal during development. `dot heal` reconciles the source → local d
 A typical output:
 
 ```
-Fleet Attestation — v0.2.500
+Fleet Attestation — v0.2.501
 
 Host           Git SHA    Policy    Tools OK   Drift   Verified
 -------------- ---------- --------- ---------- ------- --------
@@ -140,3 +145,4 @@ Only the host with the matching Age private key can decrypt. Other hosts see the
 - [Fleet Deployment Architecture](../../architecture/fleet-deployment.md) — diagrams
 - [Trust Model](02-trust-model.md)
 - [Tutorial: Deploy to a Fleet](../02-tutorials/05-deploy-fleet.md)
+{% endraw %}