conf.d/first_run.fish

@@ -22,6 +22,16 @@ end
 # leave the shell in a state that re-triggers everything next session.
 set -U __fish_config_first_run_complete 1
 
+#   ──────────────────────────── Man page symlink ──────────────────────────
+# Install fish-config.1 into the user man database once, like an install step.
+# Unconditional: standard enough that no category gate is warranted.
+set -l _man1 ~/.local/share/man/man1
+set -l _src ~/.config/fish/docs/fish-config.1
+if test -f $_src; and not test -L $_man1/fish-config.1
+    mkdir -p $_man1
+    ln -sf $_src $_man1/fish-config.1
+end
+
 #   ──────────────────────────── Welcome message ───────────────────────────
 # Printing a first-run welcome banner is opinionated (C6 greeting). The
 # first-run state variable is already set unconditionally above, so

conf.d/tricks.fish

@@ -17,16 +17,10 @@ end
 fish_add_path ~/.local/bin
 fish_add_path ~/Applications/depot_tools
 
-# Expose user-local man pages and keep fish-config.1 symlink current
+# Expose user-local man pages
 if not contains ~/.local/share/man $MANPATH
     set -gx MANPATH ~/.local/share/man $MANPATH
 end
-set -l _man1 ~/.local/share/man/man1
-set -l _src ~/.config/fish/docs/fish-config.1
-if test -f $_src; and not test -L $_man1/fish-config.1
-    mkdir -p $_man1
-    ln -sf $_src $_man1/fish-config.1
-end
 
 # Format man pages using bat (only if bat is installed)
 # Overriding $MANPAGER is opinionated (C3 overrides)

docs/fish-config.md

@@ -1972,8 +1972,9 @@ navigation.
 
 Opens the compiled docs/fish-config.1 directly via man -l, bypassing
 the pager fallback chain. If a section keyword is given, the pager opens
-at the nearest matching heading. The symlink and MANPATH are also
-configured automatically on shell start for the standard invocation:
+at the nearest matching heading. The symlink is created once on first
+run (like an install step) and MANPATH is set each session, enabling
+the standard invocation:
 
     man fish-config