diff --git a/docs/fish-config.1 b/docs/fish-config.1
index 7d5b787..6c3ac23 100644
--- a/docs/fish-config.1
+++ b/docs/fish-config.1
@@ -176,7 +176,7 @@ docs/                     Offline documentation and compiled man page
 .PP
 These variables are exported from config.fish on every interactive
 session.
-Override them in \[ti]/.config/.user-dots/fish/local.fish.
+Override them in local.fish (see Section 10, Personalization).
 .SS Environment Directories (XDG)
 .IP
 .nf
@@ -1966,7 +1966,17 @@ Place machine-specific settings that should not be committed to git in:
 .IP
 .nf
 \f[C]
-\[ti]/.config/.user-dots/fish/local.fish
+$__fish_user_dots_path/local.fish
+\f[R]
+.fi
+.PP
+\f[V]__fish_user_dots_path\f[R] defaults to
+\f[V]\[ti]/.config/.user-dots/fish\f[R].
+Set a custom location with:
+.IP
+.nf
+\f[C]
+set -U __fish_user_dots_path /path/to/your/dots/fish
 \f[R]
 .fi
 .PP
@@ -1976,15 +1986,17 @@ env vars, work-specific tool configs.
 .IP
 .nf
 \f[C]
-\[ti]/.config/.user-dots/fish/secrets.fish
+$__fish_user_dots_path/secrets.fish
 \f[R]
 .fi
 .PP
 Store API tokens, GPG keys, private credentials here.
 This file is never committed.
+It is sourced by local.fish directly, not by config.fish.
 .PP
-Both files are sourced at the end of config.fish on every interactive
-session, so they can override anything set earlier.
+\f[V]local.fish\f[R] is sourced at the end of config.fish on every
+interactive session, so it and its companion secrets.fish can override
+anything set earlier.
 .SS Overriding Configuration Variables
 .PP
 Any variable set in local.fish after the main config loads takes effect.
@@ -2621,15 +2633,25 @@ Run exec fish after a successful update to reload.
 .SH 10. PERSONALIZATION
 .PP
 Sensitive credentials and machine-specific settings are kept out of
-version control in a private directory at
-\[ti]/.config/.user-dots/fish/.
-Two files are sourced automatically by config.fish if they exist:
+version control in a private directory.
+The path defaults to \f[V]\[ti]/.config/.user-dots/fish/\f[R] but can be
+overridden:
 .IP
 .nf
 \f[C]
-\[ti]/.config/.user-dots/fish/
+set -U __fish_user_dots_path /path/to/your/dots/fish
+\f[R]
+.fi
+.PP
+config.fish sources local.fish from that directory on every interactive
+session.
+local.fish is responsible for sourcing its own secrets.fish:
+.IP
+.nf
+\f[C]
+$__fish_user_dots_path/
 ├── secrets.fish   API keys, tokens, passwords, personal identifiers
-└── local.fish     Machine-specific paths and environment variables
+└── local.fish     Machine-specific paths, env vars, and sourcing secrets
 \f[R]
 .fi
 .PP
@@ -2676,9 +2698,10 @@ abbr -a dcw \[aq]docker context use work-server\[aq]
 \f[R]
 .fi
 .PP
-Both files are sourced at the end of config.fish with an existence check
+local.fish is sourced at the end of config.fish with an existence check
 so the public config works cleanly on any machine without the private
 repo.
+local.fish in turn sources secrets.fish when it exists.
 .PP
    *   *   *   *   *
 .SH 11. VIEWING THIS MANUAL
diff --git a/docs/html/11-7-customization.html b/docs/html/11-7-customization.html
index 55de0b1..0478ce0 100644
--- a/docs/html/11-7-customization.html
+++ b/docs/html/11-7-customization.html
@@ -493,16 +493,21 @@
 Configuration</h2>
 <p>Place machine-specific settings that should not be committed to git
 in:</p>
-<pre><code>~/.config/.user-dots/fish/local.fish</code></pre>
+<pre><code>$__fish_user_dots_path/local.fish</code></pre>
+<p><code>__fish_user_dots_path</code> defaults to
+<code>~/.config/.user-dots/fish</code>. Set a custom location with:</p>
+<pre><code>set -U __fish_user_dots_path /path/to/your/dots/fish</code></pre>
 <p>Typical uses: additional PATH entries, local aliases,
 hostname-specific env vars, work-specific tool configs.</p>
 <h2 data-number="11.2" id="secrets-and-api-keys">Secrets and API
 Keys</h2>
-<pre><code>~/.config/.user-dots/fish/secrets.fish</code></pre>
+<pre><code>$__fish_user_dots_path/secrets.fish</code></pre>
 <p>Store API tokens, GPG keys, private credentials here. This file is
-never committed.</p>
-<p>Both files are sourced at the end of config.fish on every interactive
-session, so they can override anything set earlier.</p>
+never committed. It is sourced by local.fish directly, not by
+config.fish.</p>
+<p><code>local.fish</code> is sourced at the end of config.fish on every
+interactive session, so it and its companion secrets.fish can override
+anything set earlier.</p>
 <h2 data-number="11.3"
 id="overriding-configuration-variables">Overriding Configuration
 Variables</h2>
diff --git a/docs/html/14-10-personalization.html b/docs/html/14-10-personalization.html
index 54ed4eb..36614f8 100644
--- a/docs/html/14-10-personalization.html
+++ b/docs/html/14-10-personalization.html
@@ -490,11 +490,15 @@
 </nav>
 <h1 data-number="14" id="10-personalization">10. PERSONALIZATION</h1>
 <p>Sensitive credentials and machine-specific settings are kept out of
-version control in a private directory at ~/.config/.user-dots/fish/.
-Two files are sourced automatically by config.fish if they exist:</p>
-<pre><code>~/.config/.user-dots/fish/
+version control in a private directory. The path defaults to
+<code>~/.config/.user-dots/fish/</code> but can be overridden:</p>
+<pre><code>set -U __fish_user_dots_path /path/to/your/dots/fish</code></pre>
+<p>config.fish sources local.fish from that directory on every
+interactive session. local.fish is responsible for sourcing its own
+secrets.fish:</p>
+<pre><code>$__fish_user_dots_path/
 ├── secrets.fish   API keys, tokens, passwords, personal identifiers
-└── local.fish     Machine-specific paths and environment variables</code></pre>
+└── local.fish     Machine-specific paths, env vars, and sourcing secrets</code></pre>
 <p>fish_variables (auto-managed by fish) is excluded from this repo via
 .gitignore. Do not commit it.</p>
 <h2 data-number="14.1" id="secretsfish">secrets.fish</h2>
@@ -524,9 +528,10 @@ abbr -a sshw &#39;ssh you@work-server.example.com&#39;
 # Docker context shortcuts
 abbr -a dcr &#39;docker context use my-remote-server&#39;
 abbr -a dcw &#39;docker context use work-server&#39;</code></pre>
-<p>Both files are sourced at the end of config.fish with an existence
+<p>local.fish is sourced at the end of config.fish with an existence
 check so the public config works cleanly on any machine without the
-private repo.</p>
+private repo. local.fish in turn sources secrets.fish when it
+exists.</p>
 <hr />
 </body>
 </html>
diff --git a/docs/html/5-1-configuration-variables.html b/docs/html/5-1-configuration-variables.html
index 88b7b0d..8cdeb79 100644
--- a/docs/html/5-1-configuration-variables.html
+++ b/docs/html/5-1-configuration-variables.html
@@ -491,7 +491,8 @@
 <h1 data-number="5" id="1-configuration-variables">1. CONFIGURATION
 VARIABLES</h1>
 <p>These variables are exported from config.fish on every interactive
-session. Override them in ~/.config/.user-dots/fish/local.fish.</p>
+session. Override them in local.fish (see Section 10,
+Personalization).</p>
 <h2 data-number="5.1" id="environment-directories-xdg">Environment
 Directories (XDG)</h2>
 <pre><code>XDG_CONFIG_HOME    ~/.config
diff --git a/docs/wiki/1-configuration-variables.md b/docs/wiki/1-configuration-variables.md
index f388e56..0a40a30 100644
--- a/docs/wiki/1-configuration-variables.md
+++ b/docs/wiki/1-configuration-variables.md
@@ -5,7 +5,7 @@
 ---
 
 These variables are exported from config.fish on every interactive session.
-Override them in ~/.config/.user-dots/fish/local.fish.
+Override them in local.fish (see Section 10, Personalization).
 
 ## Environment Directories (XDG)
 
diff --git a/docs/wiki/10-personalization.md b/docs/wiki/10-personalization.md
index 592088d..a7847b6 100644
--- a/docs/wiki/10-personalization.md
+++ b/docs/wiki/10-personalization.md
@@ -5,12 +5,17 @@
 ---
 
 Sensitive credentials and machine-specific settings are kept out of version
-control in a private directory at ~/.config/.user-dots/fish/. Two files are
-sourced automatically by config.fish if they exist:
+control in a private directory. The path defaults to
+`~/.config/.user-dots/fish/` but can be overridden:
 
-    ~/.config/.user-dots/fish/
+    set -U __fish_user_dots_path /path/to/your/dots/fish
+
+config.fish sources local.fish from that directory on every interactive
+session. local.fish is responsible for sourcing its own secrets.fish:
+
+    $__fish_user_dots_path/
     ├── secrets.fish   API keys, tokens, passwords, personal identifiers
-    └── local.fish     Machine-specific paths and environment variables
+    └── local.fish     Machine-specific paths, env vars, and sourcing secrets
 
 fish_variables (auto-managed by fish) is excluded from this repo via
 .gitignore. Do not commit it.
@@ -48,7 +53,8 @@ wrong on any other system.
     abbr -a dcr 'docker context use my-remote-server'
     abbr -a dcw 'docker context use work-server'
 
-Both files are sourced at the end of config.fish with an existence check so
+local.fish is sourced at the end of config.fish with an existence check so
 the public config works cleanly on any machine without the private repo.
+local.fish in turn sources secrets.fish when it exists.
 
 ---
diff --git a/docs/wiki/7-customization.md b/docs/wiki/7-customization.md
index adca474..0fda0cb 100644
--- a/docs/wiki/7-customization.md
+++ b/docs/wiki/7-customization.md
@@ -8,20 +8,26 @@
 
 Place machine-specific settings that should not be committed to git in:
 
-    ~/.config/.user-dots/fish/local.fish
+    $__fish_user_dots_path/local.fish
+
+`__fish_user_dots_path` defaults to `~/.config/.user-dots/fish`. Set a
+custom location with:
+
+    set -U __fish_user_dots_path /path/to/your/dots/fish
 
 Typical uses: additional PATH entries, local aliases, hostname-specific env
 vars, work-specific tool configs.
 
 ## Secrets and API Keys
 
-    ~/.config/.user-dots/fish/secrets.fish
+    $__fish_user_dots_path/secrets.fish
 
 Store API tokens, GPG keys, private credentials here. This file is never
-committed.
+committed. It is sourced by local.fish directly, not by config.fish.
 
-Both files are sourced at the end of config.fish on every interactive
-session, so they can override anything set earlier.
+`local.fish` is sourced at the end of config.fish on every interactive
+session, so it and its companion secrets.fish can override anything set
+earlier.
 
 ## Overriding Configuration Variables