From 953aafd055fd93db29634aef02b4cec79d67a07f Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Fri, 12 Jun 2026 19:37:30 -0400
Subject: [PATCH 1/2] fix(first-run): move fish-config.1 symlink install to
 first-run
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Startup side-effects that modify the filesystem belong in first-run, not
in a recurring conf.d fragment. The symlink is now created once (like a
real install step) instead of being checked on every shell launch.

MANPATH addition stays in tricks.fish — that's an env var that must be
set each session.
---
 conf.d/first_run.fish | 10 ++++++++++
 conf.d/tricks.fish    |  8 +-------
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/conf.d/first_run.fish b/conf.d/first_run.fish
index 1939c86..d098456 100644
--- a/conf.d/first_run.fish
+++ b/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
diff --git a/conf.d/tricks.fish b/conf.d/tricks.fish
index 0191b20..a497b61 100644
--- a/conf.d/tricks.fish
+++ b/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)
-- 
2.52.0


From 682e93c794f6cd05f01abfe1ddfa92c12f0e44e0 Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Fri, 12 Jun 2026 19:37:58 -0400
Subject: [PATCH 2/2] docs: update man page symlink description to reflect
 first-run timing

---
 docs/fish-config.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/fish-config.md b/docs/fish-config.md
index aba6b65..00a06ee 100644
--- a/docs/fish-config.md
+++ b/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
 
-- 
2.52.0