@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/articles/2026-07-05-master-to-main-rename-runbook.md

@@ -1,128 +0,0 @@
----
-title: "Renaming master to main in 2026: A Zero-Downtime Runbook"
-description: A supply-chain-safe procedure for renaming the default branch of a mature open-source repository — 96 in-repo edits, a grace-period mirror workflow, zero broken install URLs.
-date: 2026-07-05
----
-
-# Renaming `master` to `main` in 2026: A Zero-Downtime Runbook for a Repository at the Heart of an Open-Source Supply Chain
-
-*Renaming the default branch of a mature repository is a supply-chain event, not a cosmetic one; done wrong, it strands `curl \| bash` install commands, breaks CI, and severs external distribution channels.*
-
-*Sebastien Rousseau · Published 5 Jul 2026 · 12 min read*
-
-## Why Default-Branch Naming Matters in 2026 #
-
-Every open-source project with a public install path publishes a URL of the form `raw.githubusercontent.com/<owner>/<repo>/<branch>/install.sh`. Every downstream consumer who has copied that URL — into a README, a Slack message, a devcontainer, a company wiki, a StackOverflow answer, a Homebrew tap, an AUR PKGBUILD, an internal Ansible playbook — has taken an implicit dependency on that branch name. Renaming the branch is a **breaking change to the project's public API surface**, whether the maintainer intended one or not.
-
-The industry moved off `master` as the default branch name years ago; new repositories default to `main`. Existing repositories, however, live with a naming inconsistency that becomes actively confusing when a maintainer has multiple projects — some on `main`, some still on `master`. The migration is unavoidable, but the operational risk profile is significant enough that most maintainers put it off indefinitely.
-
-This article documents the migration of the [.dotfiles](https://github.com/sebastienrousseau/dotfiles) repository — 60+ files with hardcoded branch references, four external distribution channels, three CI providers tracking the default branch, and a public install command bookmarked by an unknown number of downstream users. The migration was **zero-downtime**: no install command broke, no CI job failed, no downstream integration degraded. The blueprint is generalisable to any medium-complexity open-source repository.
-
-## The Branch-Rename 2026 Architecture Lens #
-
-A default-branch rename is not a single operation. It's a sequence of coordinated changes across a defined dependency graph, each with its own migration mechanism:
-
-| Layer | Design Decision | Why It Matters | Risk if Mishandled |
-|---|---|---|---|
-| **GitHub metadata** | Native rename via Settings → Branches or `POST /repos/{owner}/{repo}/branches/{branch}/rename` | GitHub auto-migrates default-branch setting, open PR targets, branch-protection assignment, ruleset targeting, and Pages source | Renaming via manual `git push :old-name` + `git push new-name` skips the auto-migration and orphans PRs |
-| **In-repo workflow triggers** | `.github/workflows/*.yml` `branches:` lists updated pre-rename | Workflows that trigger on `push:` or `pull_request:` targeting the old name silently stop firing after rename | Migration PR itself under-tested — the workflows it edits no longer fire on it |
-| **Grace-period mirror** | New workflow fast-forwards `master` from `main` on every push | Preserves `raw.githubusercontent.com/…/master/…` URLs for downstream consumers who cannot be reached | External `curl \| bash` install commands return HTTP 404 the moment `master` ceases to exist |
-| **Documentation URIs** | `mkdocs.yml` `edit_uri`, README install commands, docs prose | GitHub redirects `github.com/…/blob/master/…` automatically; `raw.githubusercontent.com/…/master/…` does **not** redirect | Docs site edit buttons point at nonexistent branches; install commands 404 |
-| **Rulesets as code** | `.github/rulesets/<branch>.json` file renamed alongside the JSON `target.include` | Machine-readable ruleset files that reference `refs/heads/master` misalign with GitHub's auto-migrated state | Configuration drift between the in-repo policy source of truth and GitHub's live enforcement |
-| **Test-suite assertions** | Regression tests that asserted `/master/` URLs in README updated to assert `/main/` | Tests written before rename fail *after* rename in the exact commit that fixes them | Migration PR shows red CI, blocking merge |
-| **External distribution** | Homebrew tap, Scoop bucket, AUR PKGBUILD — pinned to release tags, not branches | Version-pinning insulates external distribution from branch renames | Branch-pinned distribution manifests break silently on rename |
-
-## Key Branch-Rename Migration Signals #
-
-| Signal | Operational Benchmark | Reference | Technical Platform Implementation |
-|---|---|---|---|
-| **URL Reachability Post-Rename** | `HTTP 200` on both `main/install.sh` and `master/install.sh` for the full grace period | External-consumer continuity | Mirror workflow: `on: push: branches: [main]` → `git push origin main:refs/heads/master` |
-| **CI Coverage on Migration PR** | Workflow-trigger `branches:` list transitionally includes both `main` and `master` | Migration PR must be tested against the current default | `pull_request: branches: [main, master]` — remove `master` once the mirror retires |
-| **In-Repo URL Consistency** | Zero remaining `/master/` URIs on the head branch, excluding intentional mirror-preservation strings | Doc/install correctness | `git grep 'raw.githubusercontent.com/.../master/'` returns empty (or only test-fixture strings) |
-| **Ruleset File Alignment** | `.github/rulesets/*.json` filename matches its `target.include` refspec | Config-as-code hygiene | File rename via `git mv` + JSON `target.include` update in the same commit |
-| **Grace-Period Retirement Marker** | Calendar-visible tracking item with an explicit sunset date | Operational-debt visibility | GitHub issue with target date in title + calendar event (`.ics` or Google Calendar quick-add URL) |
-
-## Diagnosis: Enumerating the Blast Radius #
-
-Before touching a single file, an authoritative audit surfaces the full inventory of `master` references. On the .dotfiles repository, that surfaced **~88 mechanical replacements across 60 files**, grouped as:
-
-- **24 GitHub Actions workflow files** — trigger lists, `github.ref_name == 'master'` conditionals, `--base master` PR-creating steps, inline `@SHA # master` comments describing what commit was pinned
-- **7 `raw.githubusercontent.com/.../master/…` URLs** — README install command, `install.sh` (referencing itself in its own comment header), `bin/dot-bootstrap`, `docs/index.md`, install guide, MkDocs edit_uri, chezmoi-data JSON `$id` field
-- **~25 documentation files** — `github.com/…/blob/master/…` references in operations runbooks, security docs, architecture decision records
-- **1 ruleset-as-code file** — `.github/rulesets/master.json` with a `target.include: refs/heads/master` field
-- **1 regression test** — asserting the README contains `/master/` (a red-team catch: this test PROTECTS against accidental rename, which now needs its assertion inverted)
-- **4 legitimately-kept references** — the `gbd` bulk-branch-delete script with a `main|master` whitelist regex, the `git-primary-branch` shell function's fallback path, the release-branch check in `scripts/ops/release.sh`, and Scorecard-linter fixtures demonstrating `@master` as an anti-pattern
-
-## Remediation Sequence #
-
-The rename is executed as a five-phase sequence, each with a distinct commit or GitHub operation:
-
-**Phase 1 — Pre-migration content preparation.** A single pull request rewrites all in-repo `master` references while `master` is still the default branch. This PR must merge before any GitHub-side rename. Workflow `pull_request:` triggers gain `[main, master]` (paired) so the PR itself triggers CI against the current default. The ruleset file is renamed via `git mv` and its JSON target updated. The regression test's assertion is inverted from "must contain `/master/`" to "must contain `/main/`".
-
-**Phase 2 — GitHub-side rename.** Via UI (`Settings → Branches → Rename`) or API (`POST /repos/{owner}/{repo}/branches/master/rename`). GitHub auto-migrates default-branch setting, PR targets, branch-protection assignment, ruleset targeting, Pages source. Blocked if a branch-protection *rule pattern* targeting the new name already exists — delete the empty rule first via GraphQL:
-
-```
-gh api graphql -f query='
-mutation {
-  deleteBranchProtectionRule(input: { branchProtectionRuleId: "..." }) {
-    clientMutationId
-  }
-}'
-```
-
-**Phase 3 — Mirror workflow activation.** Trigger the pre-committed mirror workflow via `workflow_dispatch` or a small push to `main`. The workflow performs a fast-forward `git push origin main:refs/heads/master`, recreating `master` as a passive mirror. From this point forward, every push to `main` mirrors automatically.
-
-**Phase 4 — Local clone update (per-workstation).** Every developer with an active clone runs:
-
-```
-git branch -m master main
-git fetch origin
-git branch -u origin/main main
-git remote set-head origin -a
-```
-
-**Phase 5 — Retirement scheduling.** A GitHub issue with a title-embedded target date (`[2027-07-05] Retire master mirror + tighten workflow triggers to main-only`) plus a calendar reminder ensures the grace-period mirror doesn't become permanent operational debt.
-
-## Verification: URLs, CI, Docs Site #
-
-Post-rename smoke tests:
-
-```
-$ curl -sI https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh   | head -1
-HTTP/2 200
-$ curl -sI https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh | head -1
-HTTP/2 200
-```
-
-Both branch names resolve during the grace period. When the mirror is retired in 12 months, `/master/` returns 404 by design — but by then no active install command should still reference it.
-
-CI status post-rename: on the .dotfiles repository, the migration PR (`#961`) ran **70 checks green, 0 failed**, driven by the `[main, master]` trigger-list transitional configuration. The follow-up test-coverage PR (`#963`) confirmed no downstream test regression.
-
-Docs site: MkDocs `edit_uri` — updated from `edit/master/docs/` to `edit/main/docs/` — resolves correctly. `github.com/…/blob/master/…` links continue to work via GitHub's built-in redirect; `raw.githubusercontent.com/…/master/…` works via the mirror.
-
-## Return on Resilience #
-
-The commercial value of a supply-chain-safe rename is defensive, not offensive: nothing new is built, but nothing existing breaks.
-
-| Metric | Result |
-|---|---|
-| Files updated in migration PR | 97 (96 edits + 1 rename + 1 new workflow) |
-| Grace-period external URL uptime | 100% (both `/main/` and `/master/` return HTTP 200) |
-| CI checks post-rename | 70 green, 0 failed |
-| Downstream distribution channels broken | 0 (Homebrew tap, Scoop bucket, AUR pinned to tags) |
-| Local-clone update commands | 4 lines, ~5 seconds per workstation |
-| Operational debt introduced | 1 mirror workflow, retired via calendar-scheduled task 2027-07-05 |
-
-## Takeaways #
-
-1. **Land the in-repo edits before the GitHub-side rename.** Merging Phase 1 while `master` is still default gives you both a working CI baseline and a rehearsal.
-
-2. **Add the mirror workflow before renaming, not after.** The interval between the GitHub rename and the mirror's first fast-forward push is the window during which `raw.githubusercontent.com/…/master/…` returns 404. Minimising that window is a matter of ordering.
-
-3. **Update `pull_request:` triggers transitionally.** `branches: [main, master]` covers the migration PR itself (which targets the pre-rename default) and every future PR (which will target `main`). The grace-period `master` entry retires with the mirror.
-
-4. **Track retirement as an issue with an explicit sunset date.** Mirror workflows are the classic case of "temporary" becoming "permanent". A calendar event and a GitHub issue with a date-anchored title enforce end-of-life.
-
-5. **Rulesets-as-code files must be renamed alongside their JSON targets.** GitHub auto-migrates the *live* ruleset assignment; the file in your repo is the source-of-truth if you ever reapply. Both must agree.
-
-The reference implementation landed as [PR #961](https://github.com/sebastienrousseau/dotfiles/pull/961) with the retirement issue tracked at [#962](https://github.com/sebastienrousseau/dotfiles/issues/962), shipped in [v0.2.510](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.510).

package/docs/articles/index.md

@@ -1,36 +0,0 @@
----
-title: Articles
-description: Long-form writing on the design and operation of the .dotfiles framework.
----
-
-# Articles
-
-Long-form writing on the design and operation of the [.dotfiles framework](https://github.com/sebastienrousseau/dotfiles) — deep dives into performance, supply-chain safety, developer experience, and the architectural decisions that shape a mature open-source dotfiles project.
-
-<div class="grid cards" markdown>
-
-- :material-console:{ .lg .middle } **[Fish Startup in 2026](2026-07-05-fish-startup-abbr.md)**
-
-    ---
-
-    Cutting interactive shell latency by 48% with `abbr` on multi-shell dotfiles. One printf format change + one chezmoi hook = 112 ms saved per fresh terminal.
-
-    *5 Jul 2026 · 10 min read*
-
-- :material-source-branch:{ .lg .middle } **[Renaming `master` to `main`](2026-07-05-master-to-main-rename-runbook.md)**
-
-    ---
-
-    A zero-downtime runbook for a repository at the heart of an open-source supply chain. 96 in-repo edits, a 12-month mirror workflow, zero broken install URLs.
-
-    *5 Jul 2026 · 12 min read*
-
-- :material-palette:{ .lg .middle } **[Custom Documentation Sites in 2026](2026-07-05-custom-mkdocs-material-dark-theme.md)**
-
-    ---
-
-    Building a distinctive dark-themed developer reference on MkDocs Material — three files, no theme forking, WCAG AAA contrast, hash-locked build.
-
-    *5 Jul 2026 · 11 min read*
-
-</div>

package/docs/guides/INSTALL.md

@@ -1,144 +0,0 @@
----
-render_with_liquid: false
----
-
-# Install
-
-Set up on macOS, Linux, or WSL in 3 to 5 minutes.
-
-**You will need:** `git` and `curl`.
-
-**Default shell:** Fish. You can change it after you install.
-
-## Install
-
-```bash
-bash -c "$(
-  curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh
-)"
-```
-
-Then restart your terminal or run `exec $SHELL`.
-
-## Verify
-
-```bash
-dot --version        # Confirm installation
-dot doctor           # Check shell, git, and tools
-dot help             # Browse available commands
-```
-
-## Choose a shell
-
-Fish is the default shell. To switch to Zsh or Nushell, edit `~/.dotfiles/.chezmoidata.toml`:
-
-```toml
-default_shell = "zsh"
-```
-
-Supported values: `zsh`, `fish`, `nushell`.
-
-Then apply the change:
-
-```bash
-dot apply
-```
-
-## Feature flags
-
-Turn optional tools on or off after setup. Edit `.chezmoidata.toml`:
-
-```toml
-[features]
-zsh = true         # Zsh shell configuration
-fish = true        # Fish shell configuration
-nushell = true     # Nushell configuration
-nvim = true        # Neovim IDE configuration
-tmux = true        # Terminal multiplexer
-nix = true         # Nix package manager integration
-```
-
-## Update
-
-```bash
-dot update
-```
-
-## Next steps
-
-1. Run `dot learn` to take a guided tour.
-2. Add your own tweaks in `~/.config/shell/custom/`.
-3. Read the [Utilities and `dot` CLI](../reference/UTILS.md) reference.
-
----
-
-## Advanced
-
-### Local source install
-
-Clone the repo first, then run the installer from your local copy:
-
-```bash
-git clone https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles
-cd ~/.dotfiles
-./install.sh
-```
-
-### Minimal install
-
-Install only shells and core tools. This skips editor and terminal extras:
-
-```bash
-./install.sh --minimal
-```
-
-### Non-interactive install
-
-Use this mode for CI or scripts that run without user input:
-
-```bash
-DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
-  bash -c "$(
-    curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh
-  )"
-```
-
-### Nix
-
-```bash
-nix develop ~/.dotfiles/nix
-nix profile install ~/.dotfiles/nix#dot-utils
-```
-
-### Offline bundle
-
-On a machine with internet access, create a bundle:
-
-```bash
-dot bundle ~/Downloads
-```
-
-Copy the archive to the target machine. Then unpack and install:
-
-```bash
-tar --zstd -xf dotfiles_offline_bundle_*.tar.zst -P
-cd ~/.dotfiles
-./install.sh --force
-```
-
-### Uninstall
-
-```bash
-chezmoi purge
-rm -rf ~/.dotfiles
-rm -rf ~/.local/share/chezmoi ~/.local/share/dotfiles.log
-```
-
-### Signed contributions
-
-All commits must be signed. See [Contributing](https://github.com/sebastienrousseau/dotfiles/blob/main/CONTRIBUTING.md) for details.
-
----
-
-- [Troubleshooting](TROUBLESHOOTING.md)
-- [Support matrix](../reference/SUPPORT_MATRIX.md)

package/docs/guides/NEOVIM_IDE_GUIDE.md

@@ -1,61 +0,0 @@
----
-render_with_liquid: false
----
-
-# Neovim
-
-## Modern Core
-
-- **Requirement**: Neovim >= 0.11.2. The config checks this at startup.
-- **Configuration**: Modular, lazy-loaded configuration based on `lazy.nvim`.
-- **Completion**: `blink.cmp` for fast, keystroke-level completion with LSP, snippets, and path sources.
-- **UI**: Snacks.nvim dashboard, notifications, status line, buffer line, and file explorer.
-- **LSP**: Full LSP support for diagnostics, code actions, and more, managed by `mason.nvim`.
-
-## Language Support
-
-- **Rust**: Out-of-the-box support with `rustaceanvim`.
-- **Python**: Full support with `basedpyright`, `ruff`, and `venv-selector`.
-- **Web**: Support for web development with `prettier` and `eslint`.
-
-## AI Integration
-
-- **Copilot**: `copilot.lua` for code completion. Run `:Copilot auth` to sign in.
-- **Copilot Chat**: AI sidebar for asking questions and getting help (`<leader>cc`).
-
-## VS Code Parity
-
-- **Problem Panel**: `trouble.nvim` for a VS Code-like problems panel (`<leader>xx`).
-- **Search & Replace**: `nvim-spectre` for project-wide search and replace (`<leader>S`).
-- **Auto-Pairs**: Automatically closes brackets and pairs (via `blink.cmp` auto-brackets).
-- **TODOs**: Highlights `TODO` and `FIXME` comments.
-- **Session**: Auto-restores your last session.
-- **Snippets**: Native `vim.snippet` engine (Neovim 0.11+).
-
-## Keybindings
-
-| Key | Action |
-| --- | --- |
-| `<Space>ff` | Find Files |
-| `<Space>fg` | Grep (Search) text |
-| `<Space>fb` | File browser |
-| `<Space>fp` | Projects |
-| `<Space>e` | Toggle File Explorer |
-| `<Space>a` | Add file to Harpoon |
-| `<Ctrl>e` | Open Harpoon menu |
-| `gd` | Go to Definition |
-| `gr` | Go to References |
-| `<leader>ca` | Code actions |
-| `<leader>cf` | Format code |
-| `<leader>cr` | Rename symbol |
-| `<leader>tt` | Toggle terminal |
-| `<leader>tn` | Test nearest |
-| `<leader>tf` | Test file |
-| `<leader>ts` | Test suite |
-| `<F5>` | Continue (Debug) |
-| `<F10>` | Step over (Debug) |
-| `<F11>` | Step into (Debug) |
-| `<F12>` | Step out (Debug) |
-| `<leader>cc` | Toggle Copilot Chat |
-| `<leader>xx` | Toggle Diagnostics (Trouble) |
-| `<leader>S` | Toggle Spectre (Search/Replace) |

package/docs/guides/THEMING.md

@@ -1,230 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# Theming Guide
-
-The dotfiles ship a wallpaper-driven theme system that generates terminal color palettes directly from wallpaper images using K-Means clustering in CIELAB color space. One command changes the terminal, editor, window manager, GTK, desktop environment, wallpaper, and browser-facing color mode in under a second.
-
-Themes are not hand-crafted — they are extracted from whatever wallpapers are available on the system.
-
-## How Themes Work
-
-Wallpapers 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** — user-provided in `~/Pictures/Wallpapers/` (custom overrides system)
-
-`extract-theme.py` extracts dominant colors from each wallpaper using K-Means clustering in CIELAB color space, then generates a full terminal palette (16 ANSI colors, accent, bg/fg, panel, border) with WCAG contrast enforcement.
-
-`rebuild-themes.sh` orchestrates discovery → extraction → assembly into `.chezmoidata/themes.toml`. Themes are cached in `~/.cache/dotfiles/themes/` and only regenerated when wallpapers change.
-
-The `theme` key in `.chezmoidata.toml` controls the active theme. Every template references the active theme's data through `{{ $t := index .themes .theme }}`.
-
-## Switching Themes
-
-### Interactive Picker
-
-```bash
-dot theme
-```
-
-Opens an fzf picker listing every paired wallpaper theme (themes that have both `-dark` and `-light` variants). Two columns: **WALLPAPER** name and **SOURCE** (System or Custom). The current theme is marked with `✓` and `◀`. Select one and press Enter.
-
-### Direct Switch
-
-```bash
-dot theme tahoe-dark
-```
-
-Sets the theme immediately. Regenerates configs and reloads running applications.
-
-### Rebuild Themes
-
-```bash
-dot theme rebuild           # incremental (uses cache for unchanged wallpapers)
-dot theme rebuild --force   # full regeneration
-dot theme rebuild --list    # discover wallpapers without rebuilding
-```
-
-Discovers wallpapers from system + custom paths, runs K-Means extraction in parallel (4 jobs), caches generated themes in `~/.cache/dotfiles/themes/`, and writes `.chezmoidata/themes.toml`. Custom wallpapers override system wallpapers on name collision.
-
-### Under the Hood: dot-theme-sync
-
-`dot-theme-sync` handles the full switching pipeline:
-
-1. Writes the new theme name into `.chezmoidata.toml` (and `chezmoi.toml` if present).
-   If those files drift, `dot-theme-sync` now resynchronizes them before rendering because `chezmoi.toml` `[data]` overrides the source data file.
-2. Runs a targeted `chezmoi apply` on theme-dependent config files only -- much faster than a full apply.
-3. Signals running applications to reload and coordinates browser-facing theme state:
-
-```bash
-dot-theme-sync                    # Reload current theme
-dot-theme-sync macos-wave-light   # Switch to a new theme
-dot-theme-sync --full             # Full chezmoi apply instead of targeted
-```
-
-## What Changes
-
-Each theme switch touches these applications:
-
-| Application | Mechanism | What Changes |
-| :--- | :--- | :--- |
-| **Ghostty** | `chezmoi apply` + macOS app-support sync + DBus `reload-config` or runtime signal fallback | Background, foreground, all 16 ANSI colors, cursor |
-| **Tmux** | `chezmoi apply` + `source-file` | Status bar colors, pane borders, mode indicators |
-| **Niri** | `chezmoi apply` + `load-config-file` IPC | Window borders, focus ring, inactive tint |
-| **Desktop (macOS)** | `osascript` + `defaults write` + `killall` | System appearance (Light/Dark), accent color, highlight color; forces SystemUIServer/Dock/cfprefsd refresh |
-| **Wallpaper (macOS)** | `osascript` System Events | Desktop wallpaper set across all displays |
-| **Wallpaper (Linux)** | `gsettings` / `dms` / `swaybg` / `feh` | HEIC auto-converted to PNG; `picture-uri` and `picture-uri-dark` set separately |
-| **Desktop (Linux/GNOME)** | `chezmoi apply` + `gsettings` | Theme name, icon theme, color scheme preference |
-| **Safari / Chrome / Edge** | Native browser appearance follows desktop theme | Browser chrome stays aligned when using the default/native browser theme |
-| **Firefox** | `chezmoi apply` on `~/.config/firefox/user.js` | Website color scheme preference follows the active dot theme; link that file into a Firefox profile to enforce it |
-| **DMS** | `sed -i` on settings.json + IPC | Stock theme mapped to accent family, dark/light mode |
-| **Neovim** | `--remote-expr` Lua eval over socket | Colorscheme, style variant, background mode |
-| **VS Code** | `chezmoi apply` on `settings.json` | `workbench.colorTheme` value |
-| **Alacritty** | `chezmoi apply` | Full color block regeneration |
-| **Kitty** | `chezmoi apply` | Full color block regeneration |
-| **WezTerm** | `chezmoi apply` | Color scheme in Lua config |
-
-## Dark/Light Toggle
-
-```bash
-dot theme toggle
-```
-
-Toggles between the dark and light variant of the current theme family. A theme named `macos-tahoe-dark` toggles to `macos-tahoe-light`, and vice versa.
-
-## Theme Families
-
-Available themes depend on your system. Run `dot theme list` to see what's discovered. On macOS Sonoma, you'll see ~150+ themes from system wallpapers. Custom wallpapers in `~/Pictures/Wallpapers/` add more.
-
-### Rebuilding themes
-
-When wallpapers change (new system update, new custom wallpapers), regenerate:
-
-```bash
-dot theme rebuild          # Regenerate (uses cache for unchanged wallpapers)
-dot theme rebuild --force  # Force full regeneration
-dot theme rebuild --list   # List discovered wallpapers without rebuilding
-```
-
-## What works without wallpapers
-
-Theme switching is a two-tier system:
-
-**Core (always works)** — ships in the repo, no setup needed:
-
-- Terminal colors (Ghostty, Alacritty, Kitty, WezTerm, tmux)
-- Editor themes (Neovim colorscheme, VS Code)
-- macOS dark/light mode and accent color
-- Linux GNOME color-scheme, GTK theme, icon theme
-- Browser color mode (Safari, Chrome, Firefox)
-
-**Wallpapers (optional)** — user-provided, enhances the theme:
-
-- Desktop wallpaper matched to the active theme
-- Requires `~/Pictures/Wallpapers/` with files named `macos-NAME-dark.heic`
-
-If no wallpapers are present, `dot theme` applies all core changes and skips the wallpaper step. No errors, no manual config.
-
-## Wallpapers (optional)
-
-Wallpapers are not shipped in the repo. Each user sources their own and places them in `~/Pictures/Wallpapers/`:
-
-```
-macos-tahoe-dark.heic
-macos-tahoe-light.heic
-```
-
-The naming convention is `macos-NAME-APPEARANCE.heic` (or `.jpg`/`.png`). The theme picker marks themes with matching wallpapers as `[W]`.
-
-### Wallpaper guidelines
-
-- **Resolution**: 6016x6016 recommended (matches Apple's native resolution)
-- **Format**: `.heic` preferred on macOS, `.png`/`.jpg` also supported
-- **Brightness**: dark/light pairs targeting a golden ratio (1.618) relationship give balanced contrast across displays
-
-### Platform behavior
-
-| Platform | Wallpaper support | Mechanism |
-|---|---|---|
-| **macOS** | `.heic`, `.jpg`, `.png` | `osascript` (all desktops) |
-| **Linux (GNOME)** | `.png`, `.jpg` (`.heic` auto-converted) | `gsettings picture-uri` + `picture-uri-dark` |
-| **Linux (Wayland)** | `.png`, `.jpg` (`.heic` auto-converted) | `swaybg`, `feh`, or Niri/DMS IPC |
-| **WSL** | Not applicable | No compositor; terminal colors still apply |
-
-On Linux, `.heic` files are automatically converted to `.png` using `magick`, `heif-convert`, or `convert` (whichever is available). The `.png` is cached and only regenerated when the source `.heic` changes.
-
-### Using your OS default wallpapers
-
-If you don't provide custom wallpapers, your OS keeps its current desktop wallpaper. The theme still applies all color changes (terminal, editor, accent, dark/light mode). This is the expected default for most users.
-
-## Build Artifacts
-
-All build caches (Cargo, Go, pip, uv, Zig) are redirected to `/tmp/builds/` via environment variables in `mise.toml` and `cargo/config.toml`. The directory is created on shell init via `fish/conf.d/env.fish`. Build artifacts are cleared on reboot.
-
-## Troubleshooting
-
-### Theme switch did not apply
-
-Run a full apply to force all configs:
-
-```bash
-dot-theme-sync --full
-```
-
-### Ghostty did not reload
-
-Ghostty reloads via DBus (`com.mitchellh.ghostty` / `reload-config`). If DBus is unavailable, the fallback sends `SIGUSR2` to the main process and also matches the macOS app bundle path when needed. Verify Ghostty is running:
-
-```bash
-pgrep -x ghostty
-```
-
-On macOS, Ghostty may also read `~/Library/Application Support/com.mitchellh.ghostty/config`. `dot-theme-sync` now mirrors the regenerated XDG config into that location before reloading so the app-support override cannot keep an older palette active.
-
-### Neovim did not change colors
-
-`dot-theme-sync` finds Neovim server sockets at `/tmp/nvim*/0` and `$XDG_RUNTIME_DIR/nvim.*.0`. If Neovim runs with a custom `--listen` path, the auto-discovery misses it. Restart Neovim to pick up the new theme from the regenerated config.
-
-### GTK theme looks wrong
-
-GTK theme names must match installed themes exactly. Catppuccin themes use names like `catppuccin-mocha-blue-standard+default`. Install the matching GTK theme package or fall back to `Adwaita-dark` / `Adwaita`.
-
-### macOS accent or appearance did not update
-
-`dot-theme-sync` applies macOS appearance using `osascript` and accent via:
-
-```bash
-defaults write -g AppleAccentColor -int <value>
-```
-
-`dot-theme-sync` now kills `cfprefsd`, `SystemUIServer`, `Dock`, and `System Settings` after writing accent/highlight defaults to force an immediate refresh. If the UI still does not update, close and reopen System Settings.
-
-### Browser theme did not change
-
-Safari, Chrome, and Edge are coordinated through the desktop theme, so custom browser themes can override what `dot-theme-sync` is trying to align. Switch those browsers back to their native/default theme if you want them to track macOS or GTK automatically.
-
-Firefox uses the managed file at `~/.config/firefox/user.js`. Link that file into your active Firefox profile as `user.js` if you want `dot-theme-sync` to control website `prefers-color-scheme` behavior:
-
-```bash
-ln -sf ~/.config/firefox/user.js ~/.mozilla/firefox/<profile>/user.js
-```
-
-### tmux shows old colors
-
-Tmux reloads via `source-file`. If TPM plugins override colors, run:
-
-```bash
-tmux source-file ~/.config/tmux/tmux.conf
-```
-
-### Checking the active theme
-
-```bash
-grep '^theme = ' ~/.dotfiles/.chezmoidata.toml
-```
-
-This prints the current theme name. Cross-reference with `dot theme list` for available options.
-{% endraw %}