diff --git a/docs/installation.md b/docs/installation.md
index dfaa6723..45d1acc5 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -14,6 +14,17 @@ cd dotfiles
 ./install.sh
 ```
 
+### macOS Finder defaults
+
+On macOS, applying the dotfiles enables Finder's `AppleShowAllFiles` preference
+for the current user, so hidden files (including dot-prefixed files) are visible
+by default in both light and full installations. The setting is applied on the
+first apply and again whenever the Finder setup script changes.
+
+Relaunch Finder or log out and back in for the change to take effect. Setup
+does not restart Finder automatically, avoiding interruptions to file operations.
+Linux and Windows are unaffected.
+
 ## Windows (PowerShell)
 
 ### Prerequisites & manual bootstrap steps
diff --git a/home/.chezmoiscripts/darwin/run_onchange_20-configure-finder.sh b/home/.chezmoiscripts/darwin/run_onchange_20-configure-finder.sh
new file mode 100755
index 00000000..b89f9bdc
--- /dev/null
+++ b/home/.chezmoiscripts/darwin/run_onchange_20-configure-finder.sh
@@ -0,0 +1,22 @@
+#!/bin/bash
+
+set -euo pipefail
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+    exit 0
+fi
+
+# shellcheck source=home/dot_config/shell/functions/log.sh disable=SC1091
+. "${CHEZMOI_SOURCE_DIR}/dot_config/shell/functions/log.sh"
+# shellcheck disable=SC2034 # consumed by log.sh
+LOG_TAG="configure-finder"
+
+log_state "Configuring Finder to show hidden files"
+
+if ! defaults write com.apple.finder AppleShowAllFiles -bool true; then
+    log_error "Failed to enable hidden files in Finder"
+    exit 1
+fi
+
+log_result "Finder is configured to show hidden files"
+log_hint "Relaunch Finder or log out and back in for the change to take effect"
diff --git a/tests/bash/finder-defaults.bats b/tests/bash/finder-defaults.bats
new file mode 100755
index 00000000..a42d1abb
--- /dev/null
+++ b/tests/bash/finder-defaults.bats
@@ -0,0 +1,64 @@
+#!/usr/bin/env bats
+
+setup() {
+	REPO_ROOT="$(cd "${BATS_TEST_DIRNAME}/../.." && pwd)"
+	FINDER_SCRIPT="$REPO_ROOT/home/.chezmoiscripts/darwin/run_onchange_20-configure-finder.sh"
+	export CHEZMOI_SOURCE_DIR="$REPO_ROOT/home"
+	export DEFAULTS_CALLS="$BATS_TEST_TMPDIR/defaults-calls"
+	export MOCK_OS="Darwin"
+	export MOCK_DEFAULTS_STATUS=0
+	export LOG_COLOR=never LOG_LEVEL=info
+
+	mkdir -p "$BATS_TEST_TMPDIR/bin"
+	cat >"$BATS_TEST_TMPDIR/bin/uname" <<'EOF'
+#!/bin/bash
+printf '%s\n' "$MOCK_OS"
+EOF
+	cat >"$BATS_TEST_TMPDIR/bin/defaults" <<'EOF'
+#!/bin/bash
+printf '%s\n' "$*" >>"$DEFAULTS_CALLS"
+exit "$MOCK_DEFAULTS_STATUS"
+EOF
+	chmod +x "$BATS_TEST_TMPDIR/bin/uname" "$BATS_TEST_TMPDIR/bin/defaults"
+	export PATH="$BATS_TEST_TMPDIR/bin:$PATH"
+}
+
+@test "finder-defaults: enables hidden files for the current macOS user" {
+	run bash "$FINDER_SCRIPT"
+
+	[ "$status" -eq 0 ]
+	[ "$(cat "$DEFAULTS_CALLS")" = "write com.apple.finder AppleShowAllFiles -bool true" ]
+	[[ "$output" == *"Finder is configured to show hidden files"* ]]
+	[[ "$output" == *"Relaunch Finder or log out and back in"* ]]
+}
+
+@test "finder-defaults: repeated runs keep hidden files enabled" {
+	run bash "$FINDER_SCRIPT"
+	[ "$status" -eq 0 ]
+
+	run bash "$FINDER_SCRIPT"
+	[ "$status" -eq 0 ]
+	[ "$(wc -l <"$DEFAULTS_CALLS" | tr -d ' ')" -eq 2 ]
+	[ "$(sort -u "$DEFAULTS_CALLS")" = "write com.apple.finder AppleShowAllFiles -bool true" ]
+}
+
+@test "finder-defaults: skips non-macOS platforms without needing chezmoi" {
+	unset CHEZMOI_SOURCE_DIR
+	for MOCK_OS in Linux MINGW64_NT-10.0; do
+		export MOCK_OS
+		run bash "$FINDER_SCRIPT"
+
+		[ "$status" -eq 0 ]
+		[ ! -e "$DEFAULTS_CALLS" ]
+	done
+}
+
+@test "finder-defaults: reports preference write failures" {
+	export MOCK_DEFAULTS_STATUS=1
+	run bash "$FINDER_SCRIPT"
+
+	[ "$status" -eq 1 ]
+	[[ "$output" == *"Failed to enable hidden files in Finder"* ]]
+	[[ "$output" != *"Finder is configured to show hidden files"* ]]
+	[[ "$output" != *"Relaunch Finder"* ]]
+}