@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/reference/FONTS.md

@@ -1,112 +0,0 @@
----
-render_with_liquid: false
----
-
-# Font configuration
-
-How fonts are set up, rendered, and installed in these dotfiles.
-
-## Recommended fonts
-
-### Primary: JetBrains Mono Nerd Font
-
-The default font is JetBrains Mono with Nerd Font patches. It's designed for code readability, supports ligatures, includes Powerline/Nerd Font glyphs, and clearly distinguishes similar characters (`0`/`O`, `1`/`l`/`I`).
-
-### Alternatives
-
-| Font | Style | Best for |
-|------|-------|----------|
-| Fira Code | Modern | Ligature fans |
-| Cascadia Code | Microsoft | VS Code users |
-| Hack | Classic | Traditional monospace look |
-| Source Code Pro | Adobe | Clean aesthetic |
-| Iosevka | Narrow | Small screens |
-
-## Installation
-
-### macOS (Homebrew)
-
-```bash
-brew tap homebrew/cask-fonts
-brew install --cask font-jetbrains-mono-nerd-font
-
-# Or use the dot CLI
-dot fonts install
-```
-
-### Linux (manual)
-
-```bash
-wget https://github.com/ryanoasis/nerd-fonts/releases/download/v3.4.0/JetBrainsMono.zip
-unzip JetBrainsMono.zip -d ~/.local/share/fonts/
-fc-cache -fv
-```
-
-### Patching your own fonts
-
-To patch a custom font with Nerd Font glyphs:
-
-```bash
-~/.dotfiles/scripts/fonts/patch-fonts.sh /path/to/font.ttf
-```
-
-## Terminal configuration
-
-### Ghostty
-
-```text
-font-family = JetBrains Mono Nerd Font
-font-size = 14
-```
-
-### WezTerm
-
-```lua
-config.font = wezterm.font("JetBrains Mono Nerd Font")
-config.font_size = 14.0
-```
-
-### Alacritty
-
-```yaml
-font:
-  normal:
-    family: JetBrains Mono Nerd Font
-  size: 14.0
-```
-
-### Kitty
-
-```text
-font_family JetBrains Mono Nerd Font
-font_size 14.0
-```
-
-## Font size recommendations
-
-| Display | Size |
-|---------|------|
-| 13" laptop | 12-13pt |
-| 15" laptop | 13-14pt |
-| 24" monitor | 14-15pt |
-| 27" 4K monitor | 15-16pt |
-
-## Troubleshooting
-
-### Fonts not displaying correctly
-
-1. Verify the font is installed: `fc-list | grep JetBrains`
-2. Restart your terminal
-3. Double-check the terminal's font settings
-
-### Nerd Font icons missing
-
-1. Make sure you're using a Nerd Font variant (not the plain version)
-2. Confirm the terminal supports the required Unicode range
-3. Try a different Nerd Font if the issue persists
-
-### Ligatures not working
-
-1. Enable ligatures in your terminal's settings
-2. Some terminals don't support ligatures (e.g., `Terminal.app`)
-3. Ghostty, WezTerm, and Kitty all handle ligatures well

package/docs/reference/POWERSHELL_PARITY.md

@@ -1,82 +0,0 @@
----
-render_with_liquid: false
-title: "PowerShell parity matrix"
-description: "What works on Windows-native PowerShell 7.4 LTS / 7.5+ vs the bash surface."
----
-
-# PowerShell parity matrix
-
-This document tracks what is supported on Windows-native PowerShell 7.4 LTS / 7.5+ compared to the bash/zsh surface that ships on macOS and Linux. The repo's positioning has shifted (per [ROADMAP_2026 §6.9](../operations/ROADMAP_2026.md)) to call PowerShell a first-class target rather than "best effort." This page is the contract.
-
-## Support tiers
-
-| Tier | Meaning | Examples |
-|---|---|---|
-| **Full** | Native PowerShell path; tested in CI on `windows-latest`. | `dot version`, `dot help`, `dot agents check`. |
-| **WSL-bridged** | Runs under WSL2 bash with the same UX as Linux. | All `dot` subcommands, the test suite, the cold-start bench. |
-| **Bash-bridged** | The PowerShell dispatcher delegates to Git Bash or WSL bash and fails clearly when bash is unavailable. | `dot registry`, `dot fleet apply`, Unix-specific diagnostics. |
-| **N/A** | The command targets a Unix-only surface and is not exposed on PowerShell. | Wallpaper-driven theming via macOS `defaults`; Linux-only `lock-configs.sh`. |
-
-## Command-by-command matrix
-
-| Command | Windows-native | WSL2 | macOS | Linux |
-|---|---|---|---|---|
-| `dot version` | **Full (native)** — `Get-DotVersion` cmdlet in `scripts/dot/powershell/Dot.psm1`; reads `.chezmoidata.toml` directly, no bash | Full | Full | Full |
-| `dot help` | **Full (native)** — `Invoke-DotHelp`; detailed Unix command help remains bash-bridged | Full | Full | Full |
-| `dot status` | **Full (native)** — structured clean/drifted result from chezmoi | Full | Full | Full |
-| `dot diff` / `apply` / `sync` / `update` | **Full (native)** — direct, exit-code-checked chezmoi operations | Full | Full | Full |
-| `dot add` / `remove` / `init` / `cd` | **Full (native)** — direct chezmoi operations and source-path lookup | Full | Full | Full |
-| `dot doctor` | **Full (native baseline)** — PowerShell, chezmoi, git, repo data, and module checks; Unix-only diagnostics are bash-bridged | Full | Full | Full |
-| `dot agents check` | **Full (native)** — `Test-DotAgentsSync` cmdlet; CI smoke test runs the cmdlet directly | Full | Full | Full |
-| `dot agents list` | **Full (native)** — structured harness/path/rendered records | Full | Full | Full |
-| `dot agents render` | Bash-bridged | Full | Full | Full |
-| `dot env list` | **Full (native)** — mise text or JSON inventory | Full | Full | Full |
-| `dot env emit` | Bash-bridged | Full | Full | Full |
-| `dot fleet status` | **Full (native)** — node, version, OS, architecture, and drift | Full | Full | Full |
-| `dot fleet drift` / `events` / `apply` / `namespace` | Bash-bridged | Full | Full | Full |
-| `dot registry list` / `search` / `info` / `install` | Bash-bridged; Unix path is verified, checksum-pinned, and preview-first | Full | Full | Full |
-| `dot agent` / `mode` / AI commands | Bash-bridged | Full | Full | Full |
-| `dot lint` | WSL-bridged (shellcheck/shfmt are Unix-native) | Full | Full | Full |
-| `dot perf` / `health` / `tools` | Bash-bridged | Full | Full | Full |
-| `dot theme` / `wallpaper` | N/A on native Windows | Limited | Full | Full (desktop-dependent) |
-| `dot security firewall` | Bash-bridged; no native Defender mutation | N/A | Full (pf) | Full (ufw/firewalld) |
-| `dot security lock-configs` | N/A (Windows ACL model differs; tracked) | N/A | Full (`chflags uchg`) | Full (`chattr +i`) |
-| Shell startup integration | Full (`Microsoft.PowerShell_profile.ps1` ships) | Full (zsh, bash, fish) | Full (zsh, bash, fish, nu) | Full (zsh, bash, fish, nu) |
-
-## What CI verifies
-
-| Check | Platforms |
-|---|---|
-| `dot version` exits 0 | windows-latest, ubuntu-latest, macos-latest, macos-14 |
-| `dot help` exits 0 | windows-latest, ubuntu-latest, macos-latest, macos-14 |
-| `dot agents check` exits 0 | windows-latest (native), ubuntu-latest, macos-latest, macos-14 |
-| Native module import, agent-body sync, harness inventory, doctor baseline, and chezmoi diff | windows-latest |
-| Native dispatcher version, help, and agents check | windows-latest |
-| PowerShell ≥ 7.4 | windows-latest (smoke test at `tools/ci/windows-smoke-test.ps1`) |
-| PSScriptAnalyzer Error-level findings | windows-latest |
-| `chezmoi --version` exits 0 | windows-latest (via scoop), all Unix matrices |
-| `bash tools/ci/dot-cli-startup-bench.sh` median < 200ms | macos-latest |
-| `bash tools/ci/dot-cli-startup-bench.sh` median < 150ms | ubuntu-latest |
-
-## Known parity gaps
-
-These are scoped in [`ROADMAP_2026 §C5`](../operations/ROADMAP_2026.md) but not in this PR's scope:
-
-1. **Registry and fleet mutation.** Verified registry installation and multi-node fleet application still use the explicit bash bridge.
-2. **Wallpaper-driven theming.** Native Windows wallpaper extraction and application are not implemented.
-3. **Windows config locking.** There is no ACL/EFS equivalent of the Unix immutable-file operation.
-4. **Authenticode signing.** Release provenance covers the archive, but `install.ps1` and `dot.ps1` are not Authenticode-signed for enterprise execution policies.
-
-## Source-of-truth files
-
-- `.github/workflows/ci.yml` — `test-windows` job (pwsh + scoop + chezmoi + smoke)
-- `tools/ci/windows-smoke-test.ps1` — the actual gate
-- `bin/dot.ps1` and `scripts/dot/powershell/Dot.psm1` — native dispatcher and cmdlets
-- `defaults/dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl` — deployed profile
-- `scripts/dot/lib/platform.sh` — the dot_path_to_unix/native bridge (H9 audit fix)
-
-## Why this matters
-
-The 2026 trend brief flagged Windows-as-first-class as the highest-leverage move post-Codex-Windows-GA (launched 2026-03-04 with 500k waitlist → 2M WAU in 4 weeks). PowerShell 7.4 LTS retires 2026-11-10, so the gate sits at "7.4+" today and will tighten to "7.5+" in November. Documented here so the gate change is not a surprise.
-
-Generated 2026-05-16 alongside the round-2 hard audit. Maintained: when adding a `dot` subcommand, update this matrix in the same PR.

package/docs/reference/PROFILES.md

@@ -1,69 +0,0 @@
----
-render_with_liquid: false
----
-
-# Profiles and Machine Setup
-
-## Profile System
-
-You can set up each machine differently using profiles and hardware presets.
-
-### Setting Your Profile
-
-Edit `~/.config/chezmoi/chezmoi.toml`:
-
-```toml
-[data]
-profile = "laptop"        # laptop | minimal | server
-machine = "macbook-m3"    # optional: machine identifier
-```
-
-### Available Profiles
-
-| Profile | Description | What's Included |
-|---------|-------------|-----------------|
-| `laptop` | Full desktop setup (default) | All tools, AI CLIs, themes, completions |
-| `minimal` | Fast, lightweight | Core shell, git, basic aliases only |
-| `server` | Headless server | Shell, git, monitoring tools, no desktop |
-
-### Per-Machine Overrides
-
-Create a `~/.config/chezmoi/chezmoi.toml` file on each machine to override defaults:
-
-```toml
-[data]
-profile = "laptop"
-machine = "work-macbook"
-default_shell = "zsh"
-
-[data.features]
-linux_desktop = false
-zellij = true
-```
-
-### Hardware Presets
-
-The `templates/chezmoi-data/` folder has ready-made configs for common hardware:
-
-- `mac-m1.toml.example` — Apple Silicon MacBook
-- `geekom-a9.toml.example` — AMD mini PC (Linux)
-- `surface-pro-7p.toml.example` — Microsoft Surface (Linux)
-- `mac-t2-linux.toml.example` — Intel Mac running Linux
-
-Copy the one that matches your hardware:
-
-```bash
-cp templates/chezmoi-data/mac-m1.toml.example ~/.config/chezmoi/chezmoi.toml
-chezmoi apply
-```
-
-### Environment Variables
-
-You can change behavior for a single session without editing any files:
-
-| Variable | Default | Effect |
-|----------|---------|--------|
-| `DOTFILES_FAST=1` | 0 | Skip heavy layers (zinit, completions) |
-| `DOTFILES_ULTRA_FAST=1` | 0 | Bare minimum shell (aliases + prompt) |
-| `DOTFILES_AI=1` | 0 | Enable AI helper scripts |
-| `DOTFILES_PROFILE=custom` | laptop | Override profile for session |

package/docs/reference/SCREENSHOTS.md

@@ -1,121 +0,0 @@
----
-render_with_liquid: false
----
-
-# Screenshots Gallery
-
-Here's how the dotfiles look across different themes and configurations.
-
-## Theme Gallery
-
-### Catppuccin Mocha (default)
-
-The default theme. Catppuccin Mocha gives you a dark palette with warm, muted colors.
-
-```text
-Terminal: Ghostty / WezTerm / Alacritty
-Font:     JetBrains Mono Nerd Font
-Theme:    Catppuccin Mocha
-```
-
-Key colors:
-
-- Background: `#1e1e2e`
-- Foreground: `#cdd6f4`
-- Accent Blue: `#89b4fa`
-- Accent Red: `#f38ba8`
-
-### Catppuccin Latte (light)
-
-A light theme option for daytime use.
-
-```text
-Terminal: Ghostty / WezTerm / Alacritty
-Font:     JetBrains Mono Nerd Font
-Theme:    Catppuccin Latte
-```
-
-Key colors:
-
-- Background: `#eff1f5`
-- Foreground: `#4c4f69`
-- Accent Blue: `#1e66f5`
-- Accent Red: `#d20f39`
-
-## Terminal Configurations
-
-### Ghostty
-
-Modern, native terminal with GPU acceleration.
-
-- Native macOS integration
-- Fast rendering
-- Ligature support
-- Custom key bindings
-
-### WezTerm
-
-Cross-platform terminal with Lua configuration.
-
-- GPU acceleration
-- Multiple windows/tabs
-- Hyperlinks
-- Image protocol support
-
-### Alacritty
-
-Minimal, fast terminal.
-
-- Fast rendering
-- Simple YAML config
-- Vi mode
-- Cross-platform
-
-### Kitty
-
-Feature-rich terminal.
-
-- GPU rendering
-- Ligatures
-- Image support
-- Keyboard protocol
-
-## Prompt (Starship)
-
-The Starship prompt displays:
-
-- Current directory
-- Git branch and status
-- Language versions (when relevant)
-- Command duration
-- Exit status
-
-## Neovim
-
-The Neovim configuration includes:
-
-- Catppuccin theme
-- Treesitter syntax highlighting
-- LSP integration
-- Telescope fuzzy finder
-- File tree (`nvim-tree`)
-
-## tmux
-
-The tmux status bar displays:
-
-- Session name
-- Current window
-- Host name
-- Date and time
-
-## Adding Screenshots
-
-To contribute screenshots:
-
-1. Take a screenshot of your terminal.
-2. Save it as a PNG in `docs/themes/`.
-3. Add a reference in this file.
-4. Submit a PR.
-
-Recommended screenshot size: 1920x1080 or 2560x1440.

package/docs/reference/SCRIPTS.md

@@ -1,71 +0,0 @@
----
-render_with_liquid: false
----
-
-# Script Catalog
-
-Exhaustive catalog of user-facing executables installed from `dot_local/bin/`.
-
-## Core and dotfiles workflows
-
-| Command | Description |
-|---------|-------------|
-| `dot` | Primary dotfiles command-line interface |
-| `dot-ai` | Legacy AI query wrapper for local dotfiles context |
-| `dot-bootstrap` | Deterministic bootstrap entrypoint for fresh machines |
-| `dot-launch-or-focus` | Launch or focus desktop applications and sessions |
-| `dot-load-benchmark` | Measure heavy shell layer readiness in a fresh shell |
-| `dot-load-benchmark-pty` | PTY-based readiness benchmark for shell prewarm flows |
-| `dot-theme-sync` | Synchronize managed theme state across tools |
-| `update` | Update the managed dotfiles environment |
-| `tour` | Interactive guided tour of the dotfiles environment |
-
-## AI and git helpers
-
-| Command | Description |
-|---------|-------------|
-| `ai-update` | Update AI-related CLIs, runtimes, and supporting tools |
-| `ai_core` | Local AI runtime wrapper and provider fallback core |
-| `git-ai-commit` | Generate commit messages from staged changes with AI |
-| `git-ai-diff` | Review diffs and change sets with AI assistance |
-| `antigravity` | Safe wrapper for Antigravity updater execution |
-
-## Clipboard, encoding, and data inspection
-
-| Command | Description |
-|---------|-------------|
-| `b64` | Base64 encode and decode utility |
-| `bm` | Directory bookmark manager |
-| `cb` | Cross-platform clipboard helper |
-| `dtags` | Inspect Docker image tags |
-| `epoch` | Convert between human time and Unix epoch values |
-| `extract` | Archive extraction helper |
-| `hash` | Compute hashes for strings or files |
-| `hashsum` | Cross-platform cryptographic hash calculator |
-| `hex` | Hex dump and transformation helper |
-| `jsonv` | JSON validator and formatter |
-| `jwt` | JWT decoder and payload inspector |
-| `regex` | Regular expression testing helper |
-| `uuid` | UUID generation utility |
-| `yamlv` | YAML validator |
-
-## System, network, and session tools
-
-| Command | Description |
-|---------|-------------|
-| `gd` | Git diff workflow helper |
-| `gbd` | Git branch deletion workflow helper |
-| `gl` | Git log workflow helper |
-| `kill-port` | Terminate processes bound to a TCP or UDP port |
-| `lorem` | Lorem ipsum text generator |
-| `monitor` | System monitor and environment inspection helper |
-| `myip` | Show public and local IP addresses |
-| `notify` | Cross-platform desktop notification helper |
-| `open` | Cross-platform opener for files, URLs, and paths |
-| `pw` | Password and secret helper utility |
-| `rec-start` | Start shell session recording |
-| `rec-stop` | Stop shell session recording |
-| `start-niri` | Launch a Niri compositor session |
-| `tmux-sessionizer` | Fuzzy tmux session and project switcher |
-| `up` | Jump up directory levels quickly |
-| `win` | WSL bridge for launching Windows programs |

package/docs/reference/SUPPORT_MATRIX.md

@@ -1,80 +0,0 @@
----
-render_with_liquid: false
----
-
-# Support Matrix
-
-Tested platform and tool combinations for the dotfiles distribution.
-
-## Operating Systems
-
-| OS | Version | Architecture | Status | Notes |
-|----|---------|-------------|--------|-------|
-| macOS | 14+ (Sonoma) | aarch64 (Apple Silicon) | Supported | Primary dev platform |
-| macOS | 14+ (Sonoma) | x86_64 | Supported | CI tested |
-| Ubuntu | 22.04+ | x86_64 | Supported | CI tested |
-| Ubuntu | 22.04+ | aarch64 | Supported | Tested manually |
-| Debian | 12+ | x86_64 | Supported | Compatible with Ubuntu |
-| Fedora | 39+ | x86_64 | Community | Not CI tested |
-| Arch Linux | Rolling | x86_64 | Community | Not CI tested |
-| WSL2 | Ubuntu 22.04+ | x86_64 | Supported | Clipboard bridge included |
-| NixOS | 23.11+ | x86_64/aarch64 | Supported | Via Nix Flake |
-
-## Shells
-
-| Shell | Min Version | Status | Parity Tier | Notes |
-|-------|-------------|--------|-------------|-------|
-| Zsh | 5.8+ | Supported | Tier 1 (Full) | Default shell, all features |
-| Bash | 5.0+ | Supported | Tier 1 (Full) | Shared logic core |
-| Fish | 4.0+ | Supported | Tier 1 (Core CLI) | Native `dot`, `dm`, `da`, `dmc`, `datt`, and cached alias bridge |
-| Nushell | 0.98+ | Supported | Tier 1 (Core CLI) | Native `d`, `dm`, `da`, `dmc`, `datt` aliases for core workflows |
-| PowerShell | 7.5+ | Supported | Tier 1 (Core CLI) | Managed profile, `dot` wrapper, modern listing helpers, and attestation aliases |
-
-## Terminal Emulators
-
-| Terminal | Status | Notes |
-|----------|--------|-------|
-| Ghostty | Supported | Primary, custom config in `dot_config/ghostty/` |
-| 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/` |
-
-## Key Tools
-
-| Tool | Min Version | Required | Notes |
-|------|-------------|----------|-------|
-| chezmoi | 2.40+ | Yes | Core dotfiles manager |
-| git | 2.35+ | Yes | Version control |
-| curl | 7.0+ | Yes | Bootstrap installer |
-| Neovim | 0.11.2+ | No | IDE config, lazy.nvim plugins |
-| Starship | 1.17+ | No | Cross-shell prompt |
-| mise | 2024.1+ | No | Tool version manager |
-| Nix | 2.18+ | No | Reproducible environments |
-| fzf | 0.48+ | No | Fuzzy finder |
-| zoxide | 0.9+ | No | Smart directory jumper |
-| atuin | 18.0+ | No | Shell history sync |
-| pueue | 3.0+ | No | Background task manager |
-
-## CI Environments
-
-| Environment | Workflow | Platform | Status |
-|------------|----------|----------|--------|
-| GitHub Actions (Linux) | `ci.yml` | ubuntu-latest | Tested on every PR |
-| GitHub Actions (macOS) | `ci.yml` | macos-latest | Tested on every PR |
-| GitHub Actions (Enforced) | `ci-enforced.yml` | ubuntu-latest | Stricter checks |
-| Devcontainer | `devcontainer-prebuild.yml` | ubuntu-latest | Pre-built images |
-
-## Known Limitations
-
-| Platform | Limitation | Workaround |
-|----------|-----------|------------|
-| WSL2 | No native clipboard | `clip.exe`/`powershell.exe` bridge aliases |
-| NixOS | System packages conflict | Use Nix Flake exclusively |
-| Fish < 4.0 | No keyboard protocol | Upgrade to Fish 4.x |
-| Nushell | Complex aliases skipped | Core `dot` workflow remains first-class |
-| macOS Intel | Homebrew path differs | Template handles `/usr/local` vs `/opt/homebrew` |

package/docs/reference/THEMES.md

@@ -1,117 +0,0 @@
----
-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.
-
-There is no fixed theme catalog. The available themes depend on which wallpapers are present on your system. Run `dot theme list` to see what's discovered.
-
-## Source of truth
-
-Wallpapers — not `themes.toml` — are the source of truth. The system discovers wallpapers from two locations:
-
-1. **System wallpapers** — platform-native (macOS `/System/Library/Desktop Pictures/`, Linux `/usr/share/backgrounds/`)
-2. **Custom wallpapers** — `~/Pictures/Wallpapers/` (custom overrides system on name collision)
-
-`extract-theme.py` runs K-Means++ in CIELAB on each wallpaper, generates a 16-color terminal palette plus UI/app mappings, and enforces WCAG AAA contrast. `rebuild-themes.sh` orchestrates discovery → parallel extraction → assembly into `.chezmoidata/themes.toml` (cached in `~/.cache/dotfiles/themes/`, regenerated only when wallpapers change).
-
-`.chezmoidata/themes.toml` is a **generated artifact**. Do not edit it directly.
-
-## Quick Start
-
-```bash
-dot theme              # Interactive picker (paired wallpaper themes only)
-dot theme tahoe-dark   # Switch directly
-dot theme toggle       # Swap dark↔light within current family
-dot theme rebuild      # Regenerate from current wallpapers
-dot theme list         # Show paired themes with System/Custom source
-```
-
-## Runtime Apply Behavior
-
-`dot theme` writes the selected theme to `.chezmoidata.toml`, regenerates target configs through chezmoi, then attempts live reloads for running applications.
-
-- **macOS**:
-  - Applies system Light/Dark appearance via `osascript` (`System Events`)
-  - Applies the wallpaper's derived accent color via `defaults write -g AppleAccentColor` and `AppleHighlightColor`
-  - Forces UI refresh via `killall cfprefsd SystemUIServer Dock "System Settings"`
-  - Sets desktop wallpaper across all displays via `osascript`
-- **Linux**:
-  - Applies desktop color scheme through `gsettings`
-  - Sets `picture-uri` and `picture-uri-dark` separately
-  - Auto-converts HEIC → PNG via `magick`/`heif-convert`/`convert`
-  - DMS (Dank Material Shell) integration when present
-
-## Theme Naming
-
-Themes follow the pattern `<wallpaper-name>-<dark|light>`. The wallpaper filename (lowercased, hyphenated) becomes the theme family.
-
-Examples (depend on what's present on your system):
-
-| Wallpaper file | Generated themes |
-|:---|:---|
-| `~/Pictures/Wallpapers/tahoe.heic` (dynamic HEIC, 2 frames) | `tahoe-dark`, `tahoe-light` |
-| `/System/Library/Desktop Pictures/Sonoma.heic` | `sonoma-dark`, `sonoma-light` |
-| `/System/Library/Desktop Pictures/.thumbnails/Monterey Dark.heic` + `Monterey Light.heic` | `monterey-dark`, `monterey-light` |
-
-Only paired themes (with both dark and light variants) appear in `dot theme` and `dot theme list`.
-
-## Custom Wallpapers — Dynamic HEIC
-
-Custom wallpapers in `~/Pictures/Wallpapers/` ship as Apple-compatible dynamic HEIC files: a single `.heic` containing both light and dark images, tagged with `apple_desktop:apr` XMP metadata. macOS auto-switches the displayed image based on appearance mode.
-
-To merge separate dark + light pairs into a single dynamic HEIC:
-
-```bash
-bash scripts/theme/merge-wallpaper.sh           # merge all pairs in ~/Pictures/Wallpapers/
-bash scripts/theme/merge-wallpaper.sh tahoe     # merge a specific family
-bash scripts/theme/merge-wallpaper.sh --dry-run # preview only
-```
-
-## Generated Theme Schema
-
-Each theme block in the generated `themes.toml` follows this schema:
-
-```toml
-[themes.example-dark]
-mode = "dark"               # "dark" or "light"
-family = "example"          # groups dark/light variants
-macos_accent = 4            # derived from accent hue (0-6, -1=Graphite)
-wallpaper = "/path/to/wallpaper.heic"
-source = "custom"           # "custom" or "system"
-
-[themes.example-dark.term]
-bg, fg, cursor, cursor_text, sel_bg, sel_fg
-c0  .. c15                  # 16 ANSI colors
-
-[themes.example-dark.ui]
-accent, accent_text         # white text always 7:1 against accent
-error, warning, success, info
-panel, border               # contrast-bound (1.03-2.0 for panel, 1.08-3.5 for border)
-
-[themes.example-dark.app]
-nvim, nvim_style, lualine
-gtk_theme, gtk_icon, gnome_shell, gnome_gtk
-vscode, vscode_dark, vscode_light
-cat_wallpaper
-starship_palette
-```
-
-## Adding a Theme
-
-To add a new theme, add a wallpaper — there are no manual TOML edits.
-
-1. Drop a wallpaper into `~/Pictures/Wallpapers/`
-2. (Optional) Use `merge-wallpaper.sh` to combine separate dark/light files into a single dynamic HEIC
-3. Run `dot theme rebuild` to regenerate `themes.toml` (parallel K-Means extraction, ~1-4s per wallpaper)
-4. Run `dot theme <name>` to test
-5. Verify with `chezmoi diff` before applying
-
-For best results, wallpapers should be 6016×6016 dynamic HEIC with ~1.6× brightness ratio between dark and light variants (golden ratio). Lower-resolution images are auto-resized; non-paired wallpapers are skipped from the picker.
-
-## See Also
-
-- [Theming Guide](../guides/THEMING.md) — full pipeline documentation
-- [Utilities](UTILS.md) — `dot theme` command reference