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

docs/fish-config.1

@@ -977,6 +977,33 @@ view /etc/fstab
 .PP
    *   *   *   *   *
 .SS 5.4 Git and Version Control
+.SS auto-pull
+.IP
+.nf
+\f[C]
+Synopsis:  auto-pull [list]
+           auto-pull add [PATH]
+           auto-pull remove <NAME|PATH>
+           auto-pull status
+
+Manages the registry of repositories that are background fast-forwarded
+when you enter them (see \[dq]Auto-pull fast-forward\[dq] under the C2 component
+reference). The fish-config repo is always covered as a baseline. The
+registry is machine-local at \[ti]/.config/.user-dots/fish/auto-pull.list, one
+absolute path per line, and is never committed. Registry management works
+even when C2 auto-execution is disabled; only the background sync is gated.
+
+  list               Show registered repos (default)
+  add [PATH]         Register PATH\[aq]s git root (default: current repo)
+  remove <NAME|PATH> Unregister by basename or exact path
+  status             Show enabled/disabled state, repo count, list path
+
+cd \[ti]/src/qmk_firmware; and auto-pull add
+auto-pull add \[ti]/work/api
+auto-pull list
+auto-pull remove qmk_firmware
+\f[R]
+.fi
 .SS branch
 .IP
 .nf
@@ -2104,18 +2131,30 @@ paru wrapper               Every startup        Writes \[ti]/.local/bin/paru wra
 yay wrapper                Every startup        Writes \[ti]/.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
 \f[R]
 .fi
 .PP
 When C2 is disabled: no Fisher install, no theme application, no
-paru/yay wrapper generation, no automatic venv activation, and no
+paru/yay wrapper generation, no automatic venv activation, no WakaTime
-WakaTime reporting.
+reporting, and no auto-pull (the PWD handler is never registered).
 The first-run completion marker (__fish_config_first_run_complete) is
 still set so the init does not re-run on subsequent shells.
 .PP
 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.
+.PP
+Auto-pull fast-forwards opted-in repositories in the background when you
+cd into them.
+The fish-config repo is always covered; other repos are added with the
+\f[V]auto-pull\f[R] command (see its entry in the functions reference).
+It only ever fast-forwards a clean repo whose branch has an upstream
+\[em] never rebases, merges, or overwrites work \[em] so it is a no-op
+on dirty trees, divergent branches, or repos without a remote.
+The handler fires once per repo entry (not on every sub-directory cd).
+The registry is machine-local at
+\[ti]/.config/.user-dots/fish/auto-pull.list and is never committed.
 .SS C3 \[em] Key and Environment Overrides
 .PP
 These change fundamental shell behavior: how keys work, which pager

docs/html/11-7-customization.html

@@ -638,15 +638,25 @@ Catppuccin Mocha theme     First shell only     Applies theme via fish_config
 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</code></pre>
+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>
 <p>When C2 is disabled: no Fisher install, no theme application, no
-paru/yay wrapper generation, no automatic venv activation, and no
+paru/yay wrapper generation, no automatic venv activation, no WakaTime
-WakaTime reporting. The first-run completion marker
+reporting, and no auto-pull (the PWD handler is never registered). The
-(__fish_config_first_run_complete) is still set so the init does not
+first-run completion marker (__fish_config_first_run_complete) is still
-re-run on subsequent shells.</p>
+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>
+<p>Auto-pull fast-forwards opted-in repositories in the background when
+you cd into them. The fish-config repo is always covered; other repos
+are added with the <code>auto-pull</code> command (see its entry in the
+functions reference). It only ever fast-forwards a clean repo whose
+branch has an upstream — never rebases, merges, or overwrites work — so
+it is a no-op on dirty trees, divergent branches, or repos without a
+remote. The handler fires once per repo entry (not on every
+sub-directory cd). The registry is machine-local at
+~/.config/.user-dots/fish/auto-pull.list and is never committed.</p>
 <h4 data-number="11.5.1.3" id="c3--key-and-environment-overrides">C3 —
 Key and Environment Overrides</h4>
 <p>These change fundamental shell behavior: how keys work, which pager

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

@@ -685,12 +685,34 @@ view /etc/fstab</code></pre>
 <hr />
 <h2 data-number="9.4" id="54-git-and-version-control">5.4 Git and
 Version Control</h2>
-<h3 data-number="9.4.1" id="branch">branch</h3>
+<h3 data-number="9.4.1" id="auto-pull">auto-pull</h3>
+<pre><code>Synopsis:  auto-pull [list]
+           auto-pull add [PATH]
+           auto-pull remove &lt;NAME|PATH&gt;
+           auto-pull status
+
+Manages the registry of repositories that are background fast-forwarded
+when you enter them (see &quot;Auto-pull fast-forward&quot; under the C2 component
+reference). The fish-config repo is always covered as a baseline. The
+registry is machine-local at ~/.config/.user-dots/fish/auto-pull.list, one
+absolute path per line, and is never committed. Registry management works
+even when C2 auto-execution is disabled; only the background sync is gated.
+
+  list               Show registered repos (default)
+  add [PATH]         Register PATH&#39;s git root (default: current repo)
+  remove &lt;NAME|PATH&gt; Unregister by basename or exact path
+  status             Show enabled/disabled state, repo count, list path
+
+cd ~/src/qmk_firmware; and auto-pull add
+auto-pull add ~/work/api
+auto-pull list
+auto-pull remove qmk_firmware</code></pre>
+<h3 data-number="9.4.2" id="branch">branch</h3>
 <pre><code>Synopsis:  branch &lt;branch_name&gt;
 Switches to a local branch, or creates it if it does not exist.
 
 branch feature/new-ui</code></pre>
-<h3 data-number="9.4.2" id="gi">gi</h3>
+<h3 data-number="9.4.3" id="gi">gi</h3>
 <pre><code>Synopsis:  gi [-h] [-b] [-p] [-s] [-l] [targets...]
 Generates .gitignore content from the gitignore.io API with MD5-based
 deduplication (patterns already present are not re-appended).
@@ -704,7 +726,7 @@ deduplication (patterns already present are not re-appended).
 gi python,venv
 gi -b -p
 gi -s node &gt; .gitignore</code></pre>
-<h3 data-number="9.4.3" id="git-clean">git-clean</h3>
+<h3 data-number="9.4.4" id="git-clean">git-clean</h3>
 <pre><code>Synopsis:  git-clean [-f]
 Fetches and prunes the remote, fast-forwards the current branch, then
 deletes local branches whose remote tracking branch has been deleted.
@@ -714,17 +736,17 @@ Switches to main/master automatically if the current branch is orphaned.
 
 git-clean
 git-clean --force</code></pre>
-<h3 data-number="9.4.4" id="gitup">gitup</h3>
+<h3 data-number="9.4.5" id="gitup">gitup</h3>
 <pre><code>Synopsis:  gitup [args...]
 Fetches updates from the remote and shows git status. Extra args are
 forwarded to git fetch.
 
 gitup
 gitup --all</code></pre>
-<h3 data-number="9.4.5" id="gitui">gitui</h3>
+<h3 data-number="9.4.6" id="gitui">gitui</h3>
 <pre><code>Synopsis:  gitui [args...]
 Launches gitui with the Catppuccin Frappe theme pre-applied.</code></pre>
-<h3 data-number="9.4.6" id="hist">hist</h3>
+<h3 data-number="9.4.7" id="hist">hist</h3>
 <pre><code>Synopsis:  hist
 Searches shell history with fzf, inserts the selection into the command
 line, and copies it to the clipboard via wl-copy.</code></pre>

docs/html/index.html

@@ -640,6 +640,8 @@ id="toc-view">view</a></li>
 <li><a href="9-5-functions-reference.html#54-git-and-version-control"
 id="toc-54-git-and-version-control">5.4 Git and Version Control</a>
 <ul>
+<li><a href="9-5-functions-reference.html#auto-pull"
+id="toc-auto-pull">auto-pull</a></li>
 <li><a href="9-5-functions-reference.html#branch"
 id="toc-branch">branch</a></li>
 <li><a href="9-5-functions-reference.html#gi" id="toc-gi">gi</a></li>

docs/wiki/5-functions-reference.md

@@ -255,6 +255,30 @@
 
 ## 5.4 Git and Version Control
 
+### auto-pull
+
+    Synopsis:  auto-pull [list]
+               auto-pull add [PATH]
+               auto-pull remove <NAME|PATH>
+               auto-pull status
+
+    Manages the registry of repositories that are background fast-forwarded
+    when you enter them (see "Auto-pull fast-forward" under the C2 component
+    reference). The fish-config repo is always covered as a baseline. The
+    registry is machine-local at ~/.config/.user-dots/fish/auto-pull.list, one
+    absolute path per line, and is never committed. Registry management works
+    even when C2 auto-execution is disabled; only the background sync is gated.
+
+      list               Show registered repos (default)
+      add [PATH]         Register PATH's git root (default: current repo)
+      remove <NAME|PATH> Unregister by basename or exact path
+      status             Show enabled/disabled state, repo count, list path
+
+    cd ~/src/qmk_firmware; and auto-pull add
+    auto-pull add ~/work/api
+    auto-pull list
+    auto-pull remove qmk_firmware
+
 ### branch
 
     Synopsis:  branch <branch_name>

docs/wiki/7-customization.md

@@ -168,9 +168,11 @@ __fish_config_op_autoexec prevents all of them.
     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
 
 When C2 is disabled: no Fisher install, no theme application, no paru/yay
-wrapper generation, no automatic venv activation, and no WakaTime reporting.
+wrapper generation, no automatic venv activation, no WakaTime reporting, and
+no auto-pull (the PWD handler is never registered).
 The first-run completion marker (__fish_config_first_run_complete) is still
 set so the init does not re-run on subsequent shells.
 
@@ -178,6 +180,15 @@ 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.
 
+Auto-pull fast-forwards opted-in repositories in the background when you cd
+into them. The fish-config repo is always covered; other repos are added with
+the `auto-pull` command (see its entry in the functions reference). It only
+ever fast-forwards a clean repo whose branch has an upstream — never rebases,
+merges, or overwrites work — so it is a no-op on dirty trees, divergent
+branches, or repos without a remote. The handler fires once per repo entry
+(not on every sub-directory cd). The registry is machine-local at
+~/.config/.user-dots/fish/auto-pull.list and is never committed.
+
 #### C3 — Key and Environment Overrides
 
 These change fundamental shell behavior: how keys work, which pager opens,