diff --git a/.chezmoiscripts/run_onchange_seed-theme-symlinks.sh.tmpl b/.chezmoiscripts/run_onchange_seed-theme-symlinks.sh.tmpl
index 973c239..756021f 100644
--- a/.chezmoiscripts/run_onchange_seed-theme-symlinks.sh.tmpl
+++ b/.chezmoiscripts/run_onchange_seed-theme-symlinks.sh.tmpl
@@ -1,9 +1,6 @@
 #!/bin/bash
-# Seed Catppuccin theme symlinks to match current macOS appearance — but only
-# when they are ABSENT. chezmoi no longer manages these symlinks (sync-theme owns
-# them at runtime); this just bootstraps a fresh machine. Existing symlinks are
-# left untouched, so a runtime/manual selection is never clobbered.
-# (run_onchange: re-runs only if this script's content changes.)
+# Seeds Catppuccin theme symlinks for the current appearance, only when ABSENT:
+# sync-theme owns them at runtime, so an existing selection is never clobbered.
 
 set -euo pipefail
 
diff --git a/dot_local/bin/executable_dots-setup b/dot_local/bin/executable_dots-setup
index 1c75035..2594336 100644
--- a/dot_local/bin/executable_dots-setup
+++ b/dot_local/bin/executable_dots-setup
@@ -152,9 +152,8 @@ echo "${bold}Profile: ${green}${profile}${reset}"
 echo ""
 
 # ── Step 2: State-file + reload package picker ───────────────────────────────
-# fzf's change-query is async so change-query+select-all can't reliably filter
-# a group. Instead we manage selection state in a file and use execute-silent
-# + reload, which is synchronous and works for both individual and group toggles.
+# fzf's change-query is async, so group toggles keep state in a file and use
+# execute-silent + reload, which is synchronous.
 
 _state_file=$(mktemp /tmp/dots-setup-state.XXXXXX)
 _order_file=$(mktemp /tmp/dots-setup-order.XXXXXX)
@@ -328,10 +327,8 @@ touch_id_sudo=$(printf '%s\n' "${_touch_opts[@]}" | \
     --header "Enable Touch ID for sudo? (macOS 14+)")
 
 # ── Step 5: Claude billing ────────────────────────────────────────────────────
-# ANTHROPIC_API_KEY is only ever exported (see env.zsh) when you're on
-# API-key billing *and* choose to source it from 1Password. Subscription
-# (Pro/Max) users get nothing exported, so `claude` always uses subscription
-# login — no wrapper/scrubbing needed.
+# ANTHROPIC_API_KEY is exported (env.zsh) only for API-key billing sourced
+# from 1Password; subscription users get nothing, so `claude` uses its login.
 claude_api_key=false
 echo ""
 _billing_opts=(subscription api_key)
@@ -355,9 +352,7 @@ if [[ "$_claude_billing" == "api_key" ]]; then
 fi
 
 # ── Step 6: Dark-mode location (Hammerspoon darkmode.lua) ────────────────────
-# Sun times for the auto light/dark switch are computed locally from lat/long.
-# Only prompted when macos_utils (Hammerspoon) is enabled; otherwise defaults
-# (or the values already in chezmoi.toml) are kept.
+# Sun times come from lat/long. Only asked when macos_utils (Hammerspoon) is on.
 darkmode_city=$(_cfg_get darkmode_city);                   : "${darkmode_city:=Tallinn, Estonia}"
 darkmode_lat=$(_cfg_get darkmode_latitude);                : "${darkmode_lat:=59.4370}"
 darkmode_lon=$(_cfg_get darkmode_longitude);               : "${darkmode_lon:=24.7536}"
diff --git a/dot_zsh/functions.zsh.tmpl b/dot_zsh/functions.zsh.tmpl
index b2bbf6a..0263379 100644
--- a/dot_zsh/functions.zsh.tmpl
+++ b/dot_zsh/functions.zsh.tmpl
@@ -13,8 +13,7 @@ _chezmoi_sync() {
     echo "🔄 Fetching origin/main..."
     git -C "$src" fetch origin main || { echo "❌ fetch failed"; return 1; }
 
-    # checkout -B resets the main branch to origin/main regardless of current state:
-    # works from any branch, detached HEAD, or after a failed rebase.
+    # checkout -B works from any branch, detached HEAD, or a failed rebase
     git -C "$src" checkout -B main origin/main
 
     chezmoi apply
@@ -22,8 +21,7 @@ _chezmoi_sync() {
 
 # === Maintenance ===
 # Regenerate the static tool-init files (~/.zsh/*_init.zsh) + completions.
-# A `brew upgrade` can change a tool's `init` output, leaving the cache stale;
-# the run_onchange hash only catches Brewfile/plugin edits, not version bumps.
+# brew upgrade can change a tool's init output; the run_onchange hash only sees Brewfile/plugin edits.
 _regen_inits() {
     bash <(chezmoi execute-template < "$(chezmoi source-path)/.chezmoiscripts/run_onchange_generate-tool-inits.sh.tmpl")
 }
@@ -108,9 +106,8 @@ sh-add() {
 }
 
 # === Brew Drift Detection ===
-# Two-way sync: promote untracked packages into dot_Brewfile.tmpl and remove
-# stale entries (in Brewfile but no longer installed). Skipped packages are
-# persisted to .brewsync_skip so they are never prompted again.
+# Two-way sync: add untracked packages to dot_Brewfile.tmpl, drop uninstalled
+# ones. Skips persist in .brewsync_skip.
 brewsync() {
     local src brewfile tmp skip_file
     src="$(chezmoi source-path)/dot_Brewfile.tmpl"
@@ -123,7 +120,6 @@ brewsync() {
     touch "$skip_file"
 
     # ── Stale detection ──────────────────────────────────────────────────────
-    # Find packages listed in ~/.Brewfile that are no longer installed.
     local formula_list cask_list
     formula_list=$(brew list --formula 2>/dev/null)
     cask_list=$(brew list --cask 2>/dev/null)
@@ -162,11 +158,8 @@ brewsync() {
     fi
 
     # ── Untracked detection ──────────────────────────────────────────────────
-    # Use the short name (strip tap prefix) for matching: brew leaves may return
-    # "siderolabs/tap/talosctl" or just "talosctl"; brew list --cask always returns the
-    # short form (e.g. "airbattery") even when the Brewfile has the tap-qualified
-    # form (e.g. cask "lihaoyun6/tap/airbattery").  The regex ([^"'/]+/)* matches
-    # zero or more leading tap path components so both forms are detected.
+    # Match on the short name: brew leaves may or may not include the tap, casks
+    # never do, and the Brewfile may be tap-qualified; ([^"'/]+/)* covers both.
     local -a untracked=()
     while IFS= read -r pkg; do
         local short="${pkg##*/}"
@@ -177,7 +170,6 @@ brewsync() {
         command grep -qE "^cask [\"']([^\"'/]+/)*${short}[\"']" "$brewfile" || untracked+=("cask:::$cask")
     done < <(brew list --cask 2>/dev/null)
 
-    # Filter out permanently skipped entries
     local -a pending=()
     for entry in "${untracked[@]}"; do
         command grep -qxF "$entry" "$skip_file" || pending+=("$entry")
diff --git a/dot_zshrc.tmpl b/dot_zshrc.tmpl
index 819147b..c71f8dc 100644
--- a/dot_zshrc.tmpl
+++ b/dot_zshrc.tmpl
@@ -70,9 +70,7 @@ unset HISTFILE
 setopt HIST_IGNORE_SPACE AUTO_CD CORRECT
 
 # 8. Async compile (background, does not block startup)
-# Only (re)compile when the source is newer than its .zwc — `-nt` is true when
-# the target is missing too, so fresh files compile on first run. zsh updates a
-# file's mtime whenever chezmoi rewrites it, so edits are always picked up.
+# compile when source is newer than its .zwc (-nt is also true when .zwc is missing)
 {
     [[ ~/.zshrc -nt ~/.zshrc.zwc ]] && zcompile ~/.zshrc
     for f in ~/.zsh/*.zsh(N); do
diff --git a/install.sh b/install.sh
index eb75e33..72200cc 100644
--- a/install.sh
+++ b/install.sh
@@ -42,16 +42,14 @@ if ! command -v chezmoi &>/dev/null; then
 fi
 
 # --- Phase 1: init + base apply ---
-# chezmoi init clones the repo and writes ~/.config/chezmoi/chezmoi.toml with
-# safe defaults (all feature flags off). The first apply installs only base
-# packages — importantly including fzf, which dots-setup needs.
+# init writes chezmoi.toml with all flags off; the first apply installs base
+# packages only, including fzf, which dots-setup needs.
 echo "Initialising dotfiles from ${DOTFILES_REPO} (base pass)..."
 chezmoi init "$DOTFILES_REPO"
 chezmoi apply
 
 # --- Phase 2: interactive machine setup ---
-# dots-setup runs the profile wizard, writes the real chezmoi.toml, then calls
-# chezmoi apply again to install the selected packages.
+# dots-setup writes the real chezmoi.toml and applies again with the selection.
 echo ""
 echo "Launching machine setup wizard..."
 ~/.local/bin/dots-setup