From 8495cbaa240b506e33643d0417cd63b2f7999918 Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Sat, 4 Jul 2026 02:24:37 -0400
Subject: [PATCH] feat(config): auto-manage user-dots convenience symlink

Point $__fish_config_dir/user-dots at $__fish_user_dots_path on interactive
startup so the private overlay can be browsed from the fish config dir. The
link is created if missing and repointed if the path variable changes, only
ever managing a symlink (never clobbering a real file/dir). Gated as a C2
startup side-effect (__fish_config_op_autoexec) and git-ignored.

Docs: README overlay section and fish-config.md C2 table updated.
---
 .gitignore          |  1 +
 README.md           |  2 ++
 config.fish         | 16 ++++++++++++++++
 docs/fish-config.md |  8 ++++++--
 4 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index e77cadb..c086b2d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -299,3 +299,4 @@ AGENTS/
 docs/devlogs
 #   ────────────────────────────────────────────────────────
 /.cache_ggshield
+user-dots
diff --git a/README.md b/README.md
index a73e2e2..beaa023 100644
--- a/README.md
+++ b/README.md
@@ -248,6 +248,8 @@ test -f "$__fish_user_dots_path/local.fish"
     and source "$__fish_user_dots_path/local.fish"
 ```
 
+For convenience, a git-ignored `user-dots` symlink in the fish config directory is pointed at `$__fish_user_dots_path` on startup, so the overlay can be browsed from `~/.config/fish/`. It is recreated if missing and repointed if the path variable changes. This is a C2 startup side-effect (`__fish_config_op_autoexec`); it only ever manages a symlink and never clobbers a real file or directory at that path.
+
 `fish_variables` (which fish auto-manages and may contain universal variable state) is excluded from this repo via `.gitignore`.
 
 ---
diff --git a/config.fish b/config.fish
index 058e85c..e260113 100644
--- a/config.fish
+++ b/config.fish
@@ -226,6 +226,22 @@ if status is-interactive
     # Resolve user-dots path. Customize via: set -U __fish_user_dots_path /your/path
     set -q __fish_user_dots_path
         or set -l __fish_user_dots_path "$XDG_CONFIG_HOME/.user-dots/fish"
+    #   ────────────────────── user-dots convenience symlink ───────────────────
+    #   Keep $__fish_config_dir/user-dots pointing at the resolved path so it can
+    #   be browsed from the fish config dir. Git-ignored; a C2 startup side-effect.
+    #   Only ever manages a symlink — never clobbers a real file/dir placed there.
+    if __fish_config_op_enabled __fish_config_op_autoexec
+        set -l __udots_link "$__fish_config_dir/user-dots"
+        if test -d "$__fish_user_dots_path"
+            if test -L "$__udots_link"
+                test (readlink "$__udots_link") != "$__fish_user_dots_path"
+                    and ln -sfn "$__fish_user_dots_path" "$__udots_link"
+            else if not test -e "$__udots_link"
+                ln -s "$__fish_user_dots_path" "$__udots_link"
+            end
+        end
+    end
+
     #   ─────────────────────── Source machine-local config ────────────────────
     #   Sources local.fish if it exists. That file handles sourcing its own
     #   secrets.fish companion when needed.
diff --git a/docs/fish-config.md b/docs/fish-config.md
index 16619aa..264657a 100644
--- a/docs/fish-config.md
+++ b/docs/fish-config.md
@@ -1823,10 +1823,14 @@ __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
-no auto-pull (the PWD handler is never registered).
+wrapper generation, no automatic venv activation, no WakaTime 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 — a real file or directory at that path is left untouched.
 The first-run completion marker (__fish_config_first_run_complete) is still
 set so the init does not re-run on subsequent shells.