@sebastienrousseau/dotfiles 0.2.500 → 0.2.502

package/docs/manual/01-concepts/05-self-healing.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Self-Healing
 
 `.dotfiles` detects, diagnoses, and repairs configuration drift, missing tools, broken symlinks, and environmental damage — often without user intervention.
@@ -124,11 +128,13 @@ dot rollback clean        # delete snapshots older than 30 days
 ```
 
 Snapshots include:
+
 - Every file chezmoi would have overwritten
 - The previous `.chezmoidata.toml` and `chezmoi.toml`
 - A pointer to the Git SHA at apply time
 
 They do **not** include:
+
 - Generated caches (`~/.cache/`)
 - Tool binaries (Mise-managed)
 - External state (databases, remote repos)
@@ -138,7 +144,7 @@ They do **not** include:
 `dot bundle` creates a self-contained archive that can restore the workstation without network access:
 
 ```
-dotfiles-bundle-v0.2.500-20260416.tar.zst
+dotfiles-bundle-v0.2.501-20260416.tar.zst
 ├── source/              # Full git clone at current HEAD
 ├── tools/               # Pre-built chezmoi binary + mise
 ├── secrets/             # Age-encrypted snapshot of ~/.config/age/
@@ -173,6 +179,7 @@ Recovery use case: you're stranded on a new machine with no internet. Copy the b
 | Compliance (policy hash match) | 15 |
 
 Scores:
+
 - 90-100 — healthy
 - 70-89 — minor issues
 - 50-69 — needs attention

package/docs/manual/02-tutorials/01-first-install.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Tutorial: First Install
 
 End-to-end installation and verification, from zero to a fully-working environment in under 5 minutes.
@@ -16,6 +20,7 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfil
 ```
 
 The installer:
+
 1. Verifies prerequisites (`git`, `curl`, write access to `~`)
 2. Downloads chezmoi via the SHA256-verified installer
 3. Clones the dotfiles source to `~/.dotfiles`

package/docs/manual/02-tutorials/02-add-wallpaper.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Tutorial: Add a Wallpaper → Theme
 
 Drop an image. Get a fully-WCAG-AAA terminal theme.
@@ -57,6 +61,7 @@ bash scripts/theme/merge-wallpaper.sh mytheme
 ```
 
 This:
+
 1. Resizes both to 6016×6016 (preserving aspect ratio, center-cropped)
 2. Encodes both into a single `.heic` via `heif-enc`
 3. Injects `apple_desktop:apr` XMP metadata (image 0 = light, image 1 = dark)

package/docs/manual/02-tutorials/03-create-profile.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Tutorial: Create a Machine Profile
 
 Machine profiles tell chezmoi how to render templates differently on each host — display scale, keyboard layout, performance preset, available features.
@@ -236,3 +241,4 @@ Profiles let one source tree produce correctly-configured output on every host y
 - [Concept: Fleet Architecture](../01-concepts/04-fleet.md)
 - [Reference: Templates](../03-reference/04-templates.md)
 - [Reference: Feature Flags](../03-reference/05-feature-flags.md)
+{% endraw %}

package/docs/manual/02-tutorials/04-encrypt-secret.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Tutorial: Encrypt a Secret
 
 How to store an API key (or any secret) encrypted in the repository using Age and SOPS — decrypted automatically on `dot apply`.
@@ -273,3 +278,4 @@ chezmoi apply --verbose dot_tmp/stripe-key.txt
 - [Concept: Trust Model](../01-concepts/02-trust-model.md) — the security architecture
 - [Reference: Secret operations](../03-reference/01-dot-cli.md#secrets)
 - [Security: Secret management](../../security/SECRETS.md)
+{% endraw %}

package/docs/manual/02-tutorials/05-deploy-fleet.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Tutorial: Deploy to a Fleet
 
 Roll out `.dotfiles` across multiple workstations and verify they're in sync.
@@ -111,7 +115,7 @@ dot fleet attest
 Expected output:
 
 ```
-Fleet Attestation — v0.2.500
+Fleet Attestation — v0.2.501
 
 Host           Git SHA    Policy    Tools OK   Drift   Verified
 -------------- ---------- --------- ---------- ------- --------

package/docs/manual/03-reference/01-dot-cli.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Reference: The `dot` CLI
 
 Complete command reference. Every subcommand, every flag, every exit code.
@@ -147,19 +151,6 @@ dot attest [--output|-o <file>] [--sign|-s]
 
 Default output: `~/.local/state/dotfiles/attestation/YYYY-MM-DD-HHMMSS.json`. With `--sign`, the JSON is signed with the user's SSH ED25519 key.
 
-### `dot verify`
-
-Verify integrity of the installation.
-
-```
-dot verify [--security|-s] [--attestation <path>]
-```
-
-| Flag | Effect |
-|:---|:---|
-| `--security`, `-s` | Run gitleaks + signature checks + policy hash |
-| `--attestation <path>` | Verify an external attestation file |
-
 ### `dot lint`
 
 Lint shell scripts (shellcheck, shfmt).
@@ -170,24 +161,6 @@ dot lint [--path <glob>] [--strict]
 
 ## Performance
 
-### `dot benchmark`
-
-Measure shell startup time.
-
-```
-dot benchmark [--detailed|-d] [--profile|-p] [--compare|-c] [--waterfall|-w] [--runs|-r <n>]
-```
-
-| Flag | Effect |
-|:---|:---|
-| `--detailed`, `-d` | Per-module timing breakdown |
-| `--profile`, `-p` | Profile with `$SHELL -ixc ""` |
-| `--compare`, `-c` | Compare against baseline |
-| `--waterfall`, `-w` | Waterfall visualization |
-| `--runs`, `-r <n>` | Number of hyperfine runs (default 10) |
-
-Exit codes: 0 (<500ms target), 1 (regression).
-
 ### `dot perf`
 
 Quick performance snapshot.
@@ -196,17 +169,9 @@ Quick performance snapshot.
 dot perf [--json|-j] [--profile|-p] [--runs|-r <n>] [--target|-t <ms>]
 ```
 
-### `dot prewarm`
-
-Regenerate shell init caches for fast startup.
-
 ### `dot cache-refresh`
 
-Rebuild generated shell state (cold-start alternative to prewarm).
-
-### `dot clean-cache`
-
-Clear generated shell initialization caches. Next shell startup will be slow; use `dot prewarm` afterward.
+Regenerate shell caches for ultra-fast startup.
 
 ### `dot score`
 
@@ -318,11 +283,72 @@ Multi-node status, drift, and namespace.
 dot fleet              # show all known hosts
 dot fleet attest       # collect signed attestations
 dot fleet diff         # compare rendered config across hosts
-dot fleet sync         # run `dot update` on every host
+dot fleet sync         # run `dot upgrade` on every host
+dot fleet apply        # SSH out to every host in fleet.toml and run 'dot sync'
 ```
 
 Fleet hosts are configured in `~/.config/dotfiles/fleet.toml`.
 
+### `dot fleet apply`
+
+Push dotfiles state to every host registered in `~/.config/dotfiles/fleet.toml`.
+
+```
+dot fleet apply [--host <name>] [--cmd <shell>] [--dry-run] [--jobs <n>]
+```
+
+| Flag | Effect |
+|:---|:---|
+| `--host <name>` | Apply to a single host only (matches the `[hosts.<name>]` stanza key). |
+| `--cmd <shell>` | Run a custom command on every host instead of the default `dot sync && dot doctor --quiet`. **Warning:** this is arbitrary shell on remote hosts; the value is your trust boundary. |
+| `--dry-run`, `-n` | Print the resolved hosts + planned command without opening SSH. |
+| `--jobs <n>` | Parallelism (default 4). |
+
+Hostnames in `fleet.toml` are validated against `[A-Za-z0-9._@:+/-]+` before fan-out; entries containing other characters abort the apply. First-time SSH connections use `StrictHostKeyChecking=accept-new` (TOFU); pre-populate `~/.ssh/known_hosts` if your threat model requires no TOFU window.
+
+Example `fleet.toml`:
+
+```toml
+[hosts.laptop]
+ssh     = "user@laptop.local"
+profile = "workstation"
+```
+
+## Agents
+
+### `dot agents`
+
+Multi-harness AI agent configuration manager. `CLAUDE.md` is canonical; `dot agents render` keeps `AGENTS.md` (the cross-harness standard read by Codex / Copilot / Cursor / Windsurf / Amp / Devin) plus `.cursor/rules/dotfiles.mdc` and `.codex/config.toml` in sync.
+
+```
+dot agents list       # show which harnesses are recognised + their target paths
+dot agents check      # exit 0 if AGENTS.md tracks CLAUDE.md; 1 if drifted
+dot agents render     # regenerate AGENTS.md + 10 harness-specific files
+```
+
+Harnesses covered: `AGENTS.md` (canonical cross-harness), Cursor (`.cursor/rules/dotfiles.mdc`), Codex (`.codex/config.toml`), Windsurf (`.windsurf/rules.md`), Zed (`.zed/agent-config.toml`), Roo (`.roo/rules.md`), Cline (`.clinerules`), Aider (`.aider.conf.yml`), Continue (`.continuerc.json`), Jules (`.jules/system.md`), Gemini (`.gemini/GEMINI.md`).
+
+Edit `CLAUDE.md` first, then run `dot agents render`; do not hand-edit `AGENTS.md` or any of the per-harness files. The check subcommand is suitable for pre-commit hooks.
+
+## Registry
+
+### `dot registry`
+
+JSON-indexed module registry. Discover and install reusable dotfile modules from a registry hosted via GitHub Pages (or any HTTPS URL via `set-url`).
+
+```
+dot registry list                 # list modules in the configured registry
+dot registry search <query>       # filter modules by keyword
+dot registry info <name>          # full metadata for one module
+dot registry install <name>       # apply a module (scaffold today)
+dot registry url                  # show the active registry URL
+dot registry set-url <url>        # override the registry URL (HTTPS-only)
+```
+
+Default registry: `https://sebastienrousseau.github.io/dotfiles/registry.json`. Cache lives at `${XDG_CACHE_HOME:-~/.cache}/dotfiles/registry/index.json` with a 6h TTL. One-off override: `DOTFILES_REGISTRY_URL=<url> dot registry list`.
+
+The JSON contract + module-contribution flow live in [`docs/operations/REGISTRY.md`](../../operations/REGISTRY.md).
+
 ## Reference
 
 ### `dot version`
@@ -357,10 +383,6 @@ dot add --encrypt ~/.somefile          # encrypted with Age
 dot add --template ~/.somefile         # templatize
 ```
 
-### `dot remove <path>`
-
-Safely remove a managed file (removes from source and unmanages).
-
 ### `dot cd`
 
 Print the source directory path. Useful for `cd $(dot cd)`.

package/docs/manual/03-reference/02-config-files.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Reference: Configuration Files
 
 Every config file read or written by `.dotfiles`, with its schema and purpose.
@@ -28,7 +33,7 @@ Every config file read or written by `.dotfiles`, with its schema and purpose.
 
 ```toml
 # Version — bumped by version-sync.sh at release time
-dotfiles_version = "0.2.500"
+dotfiles_version = "0.2.502"
 
 # Machine preset — override in ~/.config/chezmoi/chezmoi.toml per host
 machine = ""
@@ -214,7 +219,7 @@ Agent Card (MCP A2A spec):
 ```json
 {
   "name": "dotfiles-agent",
-  "version": "0.2.500",
+  "version": "0.2.502",
   "capabilities": ["chezmoi.apply", "theme.switch", "secrets.decrypt"],
   "policy_hash": "0x7f2a..."
 }
@@ -257,3 +262,4 @@ _build/
 - [Template Variables](04-templates.md)
 - [Feature Flags](05-feature-flags.md)
 - [First Install Tutorial](../02-tutorials/01-first-install.md)
+{% endraw %}

package/docs/manual/03-reference/03-environment.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Reference: Environment Variables
 
 All environment variables that affect `.dotfiles` behaviour.

package/docs/manual/03-reference/04-templates.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Reference: Template Variables
 
 Every variable available to chezmoi templates (`.tmpl` files).
@@ -8,7 +13,7 @@ Flat top-level keys:
 
 | Variable | Type | Example |
 |:---|:---|:---|
-| `.dotfiles_version` | string | `"0.2.500"` |
+| `.dotfiles_version` | string | `"0.2.501"` |
 | `.theme` | string | `"tahoe-dark"` |
 | `.machine` | string | `"macbook-t2"` |
 | `.profile` | string | `"laptop"` |
@@ -182,3 +187,4 @@ If any template fails to render, the build breaks before merge.
 - [Chezmoi template reference](https://www.chezmoi.io/reference/templates/)
 - [Configuration Files](02-config-files.md)
 - [Create a Profile tutorial](../02-tutorials/03-create-profile.md)
+{% endraw %}

package/docs/manual/03-reference/05-feature-flags.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Reference: Feature Flags
 
 Feature flags toggle optional subsystems. Set in `.chezmoidata.toml`, override per-preset in `.chezmoidata/hardware.toml`.
@@ -6,10 +11,19 @@ Feature flags toggle optional subsystems. Set in `.chezmoidata.toml`, override p
 
 ```toml
 [features]
-dms = false                # Dank Material Shell (Niri desktop)
+alias_wrapper = false      # Wrap selected aliases with safer defaults
+dms           = true       # Dank Material Shell (Niri desktop)
+zellij        = false      # Zellij terminal multiplexer config
 linux_desktop = false      # Linux-specific desktop configs
-niri = false               # Niri window manager
-waybar = false             # Waybar status bar
+niri          = false      # Niri window manager
+waybar        = false      # Waybar status bar
+fuzzel        = false      # Fuzzel application launcher (Wayland)
+mako          = false      # Mako notification daemon (Wayland)
+foot          = false      # Foot terminal emulator (Wayland)
+kanshi        = false      # Kanshi monitor profile manager (Wayland)
+touch         = false      # Touchscreen-friendly tweaks (Surface, etc.)
+t2            = false      # Apple T2 hardware-specific tweaks
+surface       = false      # Microsoft Surface hardware-specific tweaks
 ```
 
 ## Per-Preset Overrides (`.chezmoidata/hardware.toml`)
@@ -28,6 +42,7 @@ The effective value is `mergeOverwrite` of global + preset features.
 ### `dms` — Dank Material Shell
 
 When `true`:
+
 - Configures DMS IPC for theme sync
 - Enables Quickshell templates
 - Sets up per-monitor wallpaper via `dms ipc wallpaper`
@@ -37,6 +52,7 @@ Requires: Niri + Quickshell + DMS installed.
 ### `linux_desktop` — Linux Desktop Configs
 
 When `true`:
+
 - Enables GTK 3/4 theme generation from `themes.toml`
 - Configures `gsettings color-scheme` behaviour
 - Generates desktop file entries for installed tools
@@ -46,6 +62,7 @@ No effect on macOS.
 ### `niri` — Niri Window Manager
 
 When `true`:
+
 - Generates `~/.config/niri/config.kdl`
 - Enables Niri keybindings from `keybinds.toml`
 - Configures workspace rules per preset
@@ -55,11 +72,62 @@ Requires: Niri installed.
 ### `waybar` — Waybar Status Bar
 
 When `true`:
+
 - Generates `~/.config/waybar/config.jsonc` + `style.css`
 - Hooks into theme switching via `dot-theme-sync`
 
 Requires: Waybar installed.
 
+### `alias_wrapper` — Safer Alias Defaults
+
+When `true`, opt-in wrappers replace selected aliases with confirmation-prompt
+variants (e.g., `rm -i`, `mv -i`). Default `false` for power-user ergonomics.
+
+### `zellij` — Zellij Terminal Multiplexer
+
+When `true`:
+
+- Generates `~/.config/zellij/config.kdl` from the active theme
+- Wires the `dot mux` alias to launch a profile-aware session
+
+Requires: Zellij installed.
+
+### `fuzzel` — Fuzzel Application Launcher (Wayland)
+
+When `true`, generates `~/.config/fuzzel/fuzzel.ini` using the active theme.
+Requires: Fuzzel installed (Wayland-only). No effect on macOS.
+
+### `mako` — Mako Notification Daemon (Wayland)
+
+When `true`, generates `~/.config/mako/config` with theme-derived colors.
+Requires: Mako installed (Wayland-only). No effect on macOS.
+
+### `foot` — Foot Terminal Emulator (Wayland)
+
+When `true`, generates `~/.config/foot/foot.ini` from `themes.toml`.
+Requires: Foot installed (Wayland-only). No effect on macOS.
+
+### `kanshi` — Kanshi Monitor Profile Manager (Wayland)
+
+When `true`, generates `~/.config/kanshi/config` with per-host monitor layouts.
+Requires: Kanshi installed (Wayland-only). No effect on macOS.
+
+### `touch` — Touchscreen-Friendly Tweaks
+
+When `true`, enables larger UI scaling and touch-friendly input mappings.
+Typically combined with `surface` for Microsoft Surface devices.
+
+### `t2` — Apple T2 Hardware Tweaks
+
+When `true`, enables `t2linux` kernel-module hints, audio routing fixes, and
+Touch-Bar utilities for Intel Macs with the T2 chip on Linux. Set by the
+`macbook-t2` hardware preset in `.chezmoidata/hardware.toml`.
+
+### `surface` — Microsoft Surface Hardware Tweaks
+
+When `true`, enables `linux-surface` kernel parameters, touchpad gestures, and
+pen-input mappings. Set by the `surface-pro` hardware preset.
+
 ## Using a Flag in a Template
 
 ```go
@@ -116,3 +184,4 @@ Flags can be deprecated without breaking existing hosts. The deprecation process
 
 - [Configuration Files](02-config-files.md)
 - [Create a Profile](../02-tutorials/03-create-profile.md)
+{% endraw %}

package/docs/manual/04-cookbook/01-recipes.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Cookbook: Recipes
 
 Thirty short recipes for common tasks.

package/docs/manual/04-cookbook/02-troubleshooting.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Cookbook: Troubleshooting
 
 Symptom → cause → fix.
@@ -9,6 +14,7 @@ Symptom → cause → fix.
 **Cause**: `/usr/local/bin` or `~/.local/bin` not in PATH at install time.
 
 **Fix**:
+
 ```sh
 export PATH="$HOME/.local/bin:$PATH"
 bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
@@ -19,6 +25,7 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfil
 **Cause**: Permission issue on `~/.local`.
 
 **Fix**:
+
 ```sh
 mkdir -p ~/.local/share ~/.local/state ~/.local/bin
 chmod 755 ~/.local ~/.local/share
@@ -29,6 +36,7 @@ chmod 755 ~/.local ~/.local/share
 **Cause**: Slow network or corporate proxy.
 
 **Fix**:
+
 ```sh
 export https_proxy=$HTTP_PROXY  # if applicable
 # Or pre-download chezmoi manually
@@ -43,6 +51,7 @@ apt install chezmoi             # Debian 13+
 **Cause**: Chezmoi detected local drift on a managed file.
 
 **Fix**:
+
 ```sh
 dot diff                    # see what differs
 dot apply --force           # overwrite local
@@ -55,10 +64,13 @@ dot add <path>              # import local change to source
 **Cause**: A template references a missing data field.
 
 **Fix**: Check that your `.chezmoidata.toml` has the required field. For example:
+
 ```sh
 chezmoi execute-template '{{- $hw := index .hardware .machine -}}{{ $hw.wm }}'
 ```
+
 If `machine` is not set in your `~/.config/chezmoi/chezmoi.toml`, `index` returns nil. Set:
+
 ```toml
 [data]
 machine = "macbook-t2"
@@ -69,6 +81,7 @@ machine = "macbook-t2"
 **Cause**: Cached init scripts are stale.
 
 **Fix**:
+
 ```sh
 dot clean-cache
 dot prewarm
@@ -82,6 +95,7 @@ exec $SHELL -l
 **Cause**: No wallpapers discovered, themes.toml not generated.
 
 **Fix**:
+
 ```sh
 dot theme rebuild --force
 ```
@@ -91,6 +105,7 @@ dot theme rebuild --force
 **Cause**: Theme name doesn't exist in `themes.toml`.
 
 **Fix**:
+
 ```sh
 dot theme list            # see valid names
 dot theme rebuild --force # regenerate if expected but missing
@@ -101,10 +116,12 @@ dot theme rebuild --force # regenerate if expected but missing
 **Cause**: System Settings UI cached the old value.
 
 **Fix**: `dot-theme-sync` now calls `killall cfprefsd SystemUIServer Dock "System Settings"`. If it still doesn't refresh:
+
 ```sh
 killall -KILL Dock SystemUIServer
 sudo killall -KILL cfprefsd
 ```
+
 Or log out and back in.
 
 ### Symptom: Wallpaper not applying
@@ -112,6 +129,7 @@ Or log out and back in.
 **Cause**: Wrong format or missing DE support on Linux.
 
 **Fix**:
+
 ```sh
 # Check the wallpaper file exists
 ls -la ~/Pictures/Wallpapers/
@@ -127,6 +145,7 @@ sudo apt install imagemagick-7
 **Cause**: Ghostty DBus or SIGUSR2 signaling failed.
 
 **Fix**:
+
 ```sh
 # Restart Ghostty manually, or:
 pkill -USR2 ghostty 2>/dev/null
@@ -140,6 +159,7 @@ pkill -USR2 ghostty 2>/dev/null
 **Cause**: `~/.config/age/keys.txt` missing or unreadable.
 
 **Fix**:
+
 ```sh
 ls -la ~/.config/age/keys.txt
 # Should be: -rw------- 1 user user
@@ -153,6 +173,7 @@ chmod 600 ~/.config/age/keys.txt
 **Cause**: Your Age public key isn't listed in the file's recipients.
 
 **Fix**:
+
 ```sh
 # Add your public key to .sops.yaml
 sops updatekeys path/to/file.sops.yaml
@@ -165,6 +186,7 @@ sops updatekeys path/to/file.sops.yaml
 **Cause**: A secret was committed to Git history.
 
 **Fix**:
+
 ```sh
 # Immediate mitigation
 dot verify --security   # confirm which file
@@ -184,6 +206,7 @@ git filter-repo --path <file> --invert-paths
 **Cause**: Heavy modules loaded synchronously.
 
 **Fix**:
+
 ```sh
 dot benchmark --detailed
 # Identify which module is slow
@@ -200,6 +223,7 @@ dot prewarm
 **Cause**: Multiple health issues.
 
 **Fix**:
+
 ```sh
 dot doctor --verbose    # see every failure
 dot heal                # auto-fix what's possible
@@ -211,6 +235,7 @@ dot doctor              # recheck
 **Cause**: Mise shim not activated.
 
 **Fix**:
+
 ```sh
 eval "$(mise activate zsh)"  # or fish, bash
 dot doctor                    # confirm
@@ -223,6 +248,7 @@ dot doctor                    # confirm
 **Cause**: `~/.cargo/config.toml` not managed or was overridden.
 
 **Fix**:
+
 ```sh
 chezmoi apply ~/.cargo/config.toml
 cat ~/.cargo/config.toml | grep target-dir
@@ -234,6 +260,7 @@ cat ~/.cargo/config.toml | grep target-dir
 **Cause**: Created by shell init, but shell wasn't restarted.
 
 **Fix**:
+
 ```sh
 mkdir -p /tmp/builds
 # Or restart shell
@@ -247,6 +274,7 @@ exec $SHELL -l
 **Cause**: A fleet host is unreachable.
 
 **Fix**:
+
 ```sh
 # Check connectivity to each host
 for host in macbook-t2 surface-pro geekom-a9; do
@@ -261,6 +289,7 @@ done
 **Cause**: Remote host's SSH public key not in local `~/.ssh/allowed_signers`.
 
 **Fix**:
+
 ```sh
 # On the remote host:
 ssh remote-host 'cat ~/.ssh/id_ed25519.pub'
@@ -274,6 +303,7 @@ ssh remote-host 'cat ~/.ssh/id_ed25519.pub'
 **Cause**: `shfmt` formatting differs from canonical.
 
 **Fix**:
+
 ```sh
 shfmt -w -i 2 -ci scripts/**/*.sh install.sh .chezmoitemplates/**/*.sh
 # Commit the changes
@@ -284,6 +314,7 @@ shfmt -w -i 2 -ci scripts/**/*.sh install.sh .chezmoitemplates/**/*.sh
 **Cause**: New code added without tests.
 
 **Fix**:
+
 ```sh
 bash examples/example-coverage-gate.sh
 # Identifies uncovered modules
@@ -317,3 +348,4 @@ chezmoi --version
 - [Self-Healing concept](../01-concepts/05-self-healing.md)
 - [FAQ](03-faq.md)
 - [Security: Incident Response](../../security/INCIDENT_RESPONSE.md)
+{% endraw %}