chore(docs): regenerate man page, HTML docs, and wiki

docs/fish-config.1

@@ -1802,8 +1802,9 @@ forward through the pages; Shift-Tab cycles backward.
   Sponge    \[em] sponge history-scrubbing settings: delay, successful exit
               codes, purge-only-on-exit, allow-previously-successful, and
               extra sensitive variable-name tokens
-  Paths     \[em] scrollback log directory, scrollback max files, and the
+  Paths     \[em] scrollback log directory, scrollback max files, the
-              user-dots path
+              user-dots path, and the user-dots convenience symlink toggle
+              (Dots link)
 
 Toggle rows use ← → (or h/l) along an OFF ← DEFAULT → ON scale; DEFAULT
 erases the variable so the master switch / built-in default applies. Value
@@ -2089,6 +2090,16 @@ set -U __fish_user_dots_path /path/to/your/dots/fish
 .PP
 Typical uses: additional PATH entries, local aliases, hostname-specific
 env vars, work-specific tool configs.
+.PP
+For convenience, a git-ignored \f[V]user-dots\f[R] symlink in the fish
+config directory tracks \f[V]$__fish_user_dots_path\f[R] so the overlay
+can be browsed from \f[V]\[ti]/.config/fish/\f[R].
+It is created if missing and repointed if the path changes.
+Opt out by setting \f[V]__fish_user_dots_symlink\f[R] to a falsy value,
+or toggling \[lq]Dots link\[rq] off on the config-settings Paths page
+\[em] this stops generation and removes any existing link.
+It only ever manages a symlink and never clobbers a real file or
+directory at that path.
 .SS Secrets and API Keys
 .IP
 .nf
@@ -2272,12 +2283,22 @@ yay wrapper                Every startup        Writes \[ti]/.local/bin/yay wrap
 Python venv activation     On every cd          Sources .venv/bin/activate.fish
 WakaTime command hook      On every command     Reports to WakaTime API
 Auto-pull fast-forward     On entering a repo   Background ff-only git pull
+user-dots symlink          Every startup        Links $__fish_config_dir/user-dots
+                                                to $__fish_user_dots_path
 \f[R]
 .fi
 .PP
 When C2 is disabled: no Fisher install, no theme application, no
 paru/yay wrapper generation, no automatic venv activation, no WakaTime
-reporting, and no auto-pull (the PWD handler is never registered).
+reporting, no auto-pull (the PWD handler is never registered), and the
+user-dots convenience symlink is not created.
+The symlink is git-ignored and only ever managed as a symlink \[em] a
+real file or directory at that path is left untouched.
+The symlink has its own opt-out independent of C2: set
+__fish_user_dots_symlink to a falsy value (or toggle \[lq]Dots link\[rq]
+off on the config-settings Paths page) to stop generating it and remove
+any existing link \[em] honoured even when C2 is enabled.
+Managed by the __fish_user_dots_link helper.
 The first-run completion marker (__fish_config_first_run_complete) is
 still set so the init does not re-run on subsequent shells.
 .PP

docs/html/11-7-customization.html

@@ -499,6 +499,14 @@ in:</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>
+<p>For convenience, a git-ignored <code>user-dots</code> symlink in the
+fish config directory tracks <code>$__fish_user_dots_path</code> so the
+overlay can be browsed from <code>~/.config/fish/</code>. It is created
+if missing and repointed if the path changes. Opt out by setting
+<code>__fish_user_dots_symlink</code> to a falsy value, or toggling
+"Dots link" off on the config-settings Paths page — this stops
+generation and removes any existing link. It only ever manages a symlink
+and never clobbers a real file or directory at that path.</p>
 <h2 data-number="11.2" id="secrets-and-api-keys">Secrets and API
 Keys</h2>
 <pre><code>$__fish_user_dots_path/secrets.fish</code></pre>
@@ -644,12 +652,21 @@ paru wrapper               Every startup        Writes ~/.local/bin/paru wrapper
 yay wrapper                Every startup        Writes ~/.local/bin/yay wrapper
 Python venv activation     On every cd          Sources .venv/bin/activate.fish
 WakaTime command hook      On every command     Reports to WakaTime API
-Auto-pull fast-forward     On entering a repo   Background ff-only git pull</code></pre>
+Auto-pull fast-forward     On entering a repo   Background ff-only git pull
+user-dots symlink          Every startup        Links $__fish_config_dir/user-dots
+                                                to $__fish_user_dots_path</code></pre>
 <p>When C2 is disabled: no Fisher install, no theme application, no
 paru/yay wrapper generation, no automatic venv activation, no WakaTime
-reporting, and no auto-pull (the PWD handler is never registered). The
+reporting, no auto-pull (the PWD handler is never registered), and the
-first-run completion marker (__fish_config_first_run_complete) is still
+user-dots convenience symlink is not created. The symlink is git-ignored
-set so the init does not re-run on subsequent shells.</p>
+and only ever managed as a symlink — a real file or directory at that
+path is left untouched. The symlink has its own opt-out independent of
+C2: set __fish_user_dots_symlink to a falsy value (or toggle "Dots link"
+off on the config-settings Paths page) to stop generating it and remove
+any existing link — honoured even when C2 is enabled. Managed by the
+__fish_user_dots_link helper. The first-run completion marker
+(__fish_config_first_run_complete) is still set so the init does not
+re-run on subsequent shells.</p>
 <p>Python venv activation fires on every directory change. If a
 directory uses direnv (.envrc present), direnv takes priority and
 auto-venv is skipped for that directory.</p>

docs/html/9-5-functions-reference.html

@@ -1227,8 +1227,9 @@ forward through the pages; Shift-Tab cycles backward.
   Sponge    — sponge history-scrubbing settings: delay, successful exit
               codes, purge-only-on-exit, allow-previously-successful, and
               extra sensitive variable-name tokens
-  Paths     — scrollback log directory, scrollback max files, and the
+  Paths     — scrollback log directory, scrollback max files, the
-              user-dots path
+              user-dots path, and the user-dots convenience symlink toggle
+              (Dots link)
 
 Toggle rows use ← → (or h/l) along an OFF ← DEFAULT → ON scale; DEFAULT
 erases the variable so the master switch / built-in default applies. Value

docs/wiki/5-functions-reference.md

@@ -917,8 +917,9 @@
       Sponge    — sponge history-scrubbing settings: delay, successful exit
                   codes, purge-only-on-exit, allow-previously-successful, and
                   extra sensitive variable-name tokens
-      Paths     — scrollback log directory, scrollback max files, and the
+      Paths     — scrollback log directory, scrollback max files, the
-                  user-dots path
+                  user-dots path, and the user-dots convenience symlink toggle
+                  (Dots link)
 
     Toggle rows use ← → (or h/l) along an OFF ← DEFAULT → ON scale; DEFAULT
     erases the variable so the master switch / built-in default applies. Value

docs/wiki/7-customization.md

@@ -18,6 +18,14 @@ custom location with:
 Typical uses: additional PATH entries, local aliases, hostname-specific env
 vars, work-specific tool configs.
 
+For convenience, a git-ignored `user-dots` symlink in the fish config
+directory tracks `$__fish_user_dots_path` so the overlay can be browsed from
+`~/.config/fish/`. It is created if missing and repointed if the path changes.
+Opt out by setting `__fish_user_dots_symlink` to a falsy value, or toggling
+"Dots link" off on the config-settings Paths page — this stops generation and
+removes any existing link. It only ever manages a symlink and never clobbers a
+real file or directory at that path.
+
 ## Secrets and API Keys
 
     $__fish_user_dots_path/secrets.fish
@@ -175,10 +183,18 @@ __fish_config_op_autoexec prevents all of them.
     Python venv activation     On every cd          Sources .venv/bin/activate.fish
     WakaTime command hook      On every command     Reports to WakaTime API
     Auto-pull fast-forward     On entering a repo   Background ff-only git pull
+    user-dots symlink          Every startup        Links $__fish_config_dir/user-dots
+                                                    to $__fish_user_dots_path
 
 When C2 is disabled: no Fisher install, no theme application, no paru/yay
-wrapper generation, no automatic venv activation, no WakaTime reporting, and
+wrapper generation, no automatic venv activation, no WakaTime reporting,
-no auto-pull (the PWD handler is never registered).
+no auto-pull (the PWD handler is never registered), and the user-dots
+convenience symlink is not created. The symlink is git-ignored and only ever
+managed as a symlink — a real file or directory at that path is left untouched.
+The symlink has its own opt-out independent of C2: set __fish_user_dots_symlink
+to a falsy value (or toggle "Dots link" off on the config-settings Paths page)
+to stop generating it and remove any existing link — honoured even when C2 is
+enabled. Managed by the __fish_user_dots_link helper.
 The first-run completion marker (__fish_config_first_run_complete) is still
 set so the init does not re-run on subsequent shells.