From 618ce00f9ea64bd4f6d42ad852d570adf4ba1715 Mon Sep 17 00:00:00 2001
From: Rootiest <chris@rootiest.com>
Date: Mon, 31 Aug 2026 21:56:15 -0400
Subject: [PATCH 1/2] docs(index): full audit of the config-help keyword index

Cover the ~50 previously-unindexed headings (function reference entries
like play-media, steam-dl, bd-pull, cffetch/ffetch, config-toggle, dops,
rand_string, fish_prompt/fish_mode_prompt/fish_right_prompt, lD, mv, p,
fast/fast-cli, gip4/gip6, fzf-update, sponge_filter_secrets,
fzf_configure_bindings, ld; the C1-C6 component sub-category headings
filesystem/network/monitor/shell-tools/dev-tools,
plugin-management/pkg-wrappers/venv/telemetry/sync,
key-bindings/environment/prompt, terminal-abbrs/window-mgmt/
notifications/history-logs/pkg-upgrade, terminal-capture/
multiplexer-capture/pkg-logs, first-run/greeting-message; plus
Config Variables' "Other", the Integrations "Scrollback History", the
dependency catalog's Optional/Terminal Emulators tiers, the C0/always
override note, and "Reading the source directly").

Expanded aliases for existing headings: play-media also reachable as
video/audio/mpv/vlc, steam-dl as steam, cffetch/ffetch share fetch/
fastfetch/neofetch/sysinfo, rand_string as random/password/randomword,
gip4/gip6 as ipv4/ipv6, dops as docker-ps, ld as lazydocker, bd-pull as
beads, fast-cli as speedtest, sponge_filter_secrets as secret-filter.

Fixed two pre-existing duplicate normalized keys (key-bindings/
keybindings and man-page/manpage both collapsed to a single entry) and
repointed config-toggle from the generic config-settings heading to its
own dedicated "### config-toggle" heading now that one exists.

Judgment calls on ambiguous/repeated heading text (left unindexed, or
indexed via a distinguishing keyword instead of the literal name):
- "### Sub-categories" repeats 7 times (once per opinionated-components
  overview and once per C1-C6 page); an index entry pointing at that
  text always resolves to the first occurrence, so none of the 7 are
  indexed under that name. Each parent (C1-C6, and the Minimal Mode
  section) already has its own keyword.
- "### search" appears twice: the pkg search subcommand (kept, existing
  `search` key) and the C1 command-shadow sub-category. The C1 one
  isn't separately reachable for the same reason.
- "## Integrations" appears twice (Section 1 integrations writeup and
  the Dependency Catalog's Integrations tier table); only the first
  (already indexed) is reachable.
- Where a C1-C6 sub-category heading text collides after normalization
  with an existing higher-value keyword (key-bindings, network,
  notifications, venv), the new entry uses a distinguishing keyword
  (bindings-toggle, network-shadow, notifications-toggle, venv-toggle)
  instead of contesting the existing one.
- `prompt` now points at the fuller "## Prompt and Theme" section
  rather than the one-line C3 sub-category blurb; the latter is
  reachable via `prompt-toggle`.
---
 docs/fish-config.index | 93 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 83 insertions(+), 10 deletions(-)

diff --git a/docs/fish-config.index b/docs/fish-config.index
index c9d2373..5f9adb8 100644
--- a/docs/fish-config.index
+++ b/docs/fish-config.index
@@ -27,6 +27,7 @@ scrollback=## Scrollback History
 __fish_scrollback_history_dir=## Scrollback History
 __fish_scrollback_history_max_files=## Scrollback History
 scrollback-dir=## Scrollback History
+misc-vars=## Other
 
 # ── Section 2: PATH ───────────────────────────────────────────
 path=# 2. PATH SETUP
@@ -34,7 +35,6 @@ path=# 2. PATH SETUP
 # ── Section 3: Key Bindings ───────────────────────────────────
 keybindings=# 3. KEY BINDINGS
 bindings=# 3. KEY BINDINGS
-key-bindings=# 3. KEY BINDINGS
 keys=# 3. KEY BINDINGS
 fzf-bindings=## FZF Bindings (bundled from PatrickF1/fzf.fish)
 fzf=## FZF Bindings (bundled from PatrickF1/fzf.fish)
@@ -67,6 +67,8 @@ cat=### cat
 copy=### copy
 du=### du
 dusize=### dusize
+dirs=### lD
+lsdirs=### lD
 ls=### ls
 lsr=### lsr
 lss=### lss
@@ -76,6 +78,7 @@ ltr=### ltr
 lx=### lx
 mkdir=### mkdir
 mkcd=### mkcd
+mv=### mv
 poke=### poke
 rm=### rm
 rg=### rg
@@ -110,6 +113,7 @@ parur=### parur
 deps=## 5.6 Dependency Management
 fish-deps=### fish-deps
 check-deps=### check_fish_deps
+fzf-update=### fzf-update
 system=## 5.7 System and Monitoring
 top=### top
 swapstat=### swapstat
@@ -125,19 +129,33 @@ split=### split
 spwin=### spwin
 detach=### detach
 bkg=### bkg
+fish-mode-prompt=### fish_mode_prompt
+fish-prompt=### fish_prompt
+fish-right-prompt=### fish_right_prompt
+right-prompt=### fish_right_prompt
 jobrunner=### jobrunner
 jr=### jr
 ssh=### ssh
 clipboard=## 5.9 Clipboard
 copy-fn=### y
+p=### p
 paste=### paste
 network=## 5.10 Network
+fast=### fast
+fast-cli=### fast-cli
+speedtest=### fast-cli
 gip=### gip
+gip4=### gip4
+ipv4=### gip4
+gip6=### gip6
+ipv6=### gip6
 ping=### ping
 qr=### qr
 logging=## 5.11 Pager and Logging
 logs=### logs
 smart-exit=### smart_exit
+sponge-filter-secrets=### sponge_filter_secrets
+secret-filter=### sponge_filter_secrets
 ai=## 5.12 AI and Developer Tools
 antigravity-ide=### antigravity-ide
 agy=### agy
@@ -152,28 +170,52 @@ devlogs=### agents-init
 claude-cli=### claude
 claude-docs=### claude-docs
 claude-pr=### claude-pr
+dops=### dops
+docker-ps=### dops
 qc=### qc
 quick-chat=### qc
 aichat=### qc
 superpowers=### superpowers
 media=## 5.13 Media and Utilities
 dng2avif=### dng2avif
+play-media=### play-media
+video=### play-media
+audio=### play-media
+mpv=### play-media
+vlc=### play-media
 spark=### spark
+steam-dl=### steam-dl
+steam=### steam-dl
 yt-dlp=### yt-dlp
 miscfns=## 5.14 Miscellaneous
+bash=### bash
+bd-pull=### bd-pull
+beads=### bd-pull
+cffetch=### cffetch
+fastfetch=### ffetch
+neofetch=### cffetch
+sysinfo=### cffetch
+cheat=### cheat
 config-help=### config-help
+config-update=### config-update
+config-settings=### config-settings
+config-toggle=### config-toggle
+toggle=### config-settings
+dockup=### dockup
+fetch=### cffetch
+ffetch=### ffetch
+fzf_configure_bindings=### fzf_configure_bindings
+joplin=### joplin
+ld=### ld
+lazydocker=### ld
 open-url=### open-url
 url-open=### open-url
 repo-open=### repo-open
 open-repo=### repo-open
-config-update=### config-update
-config-settings=### config-settings
-config-toggle=### config-settings
-toggle=### config-settings
-bash=### bash
-cheat=### cheat
-dockup=### dockup
-joplin=### joplin
+rand_string=### rand_string
+random=### rand_string
+password=### rand_string
+randomword=### rand_string
 replay=### replay
 tmux=### tmux-clean
 wake-lock=### wake-lock
@@ -208,6 +250,7 @@ pager-hierarchy=## Pager Hierarchy
 shell-aliases=## 4.11 Shell Aliases
 kitty-logging=### kitty-logging
 watcher=### kitty-logging
+kitty-scrollback=### Scrollback History
 
 # ── Section 6: Dependency Catalog ────────────────────────────
 catalog=# 6. DEPENDENCY CATALOG
@@ -215,6 +258,8 @@ deps-catalog=# 6. DEPENDENCY CATALOG
 required=## Required
 integrations=## Integrations
 recommended=## Recommended
+optional-deps=## Optional
+terminal-emulators=## Terminal Emulators
 install-methods=## Install Methods
 
 # ── Section 7: Customization ──────────────────────────────────
@@ -233,17 +278,38 @@ opt-out=## Opinionated Components (Minimal Mode)
 toggles=## Opinionated Components (Minimal Mode)
 component-reference=# 8. COMPONENTS REFERENCE
 components=# 8. COMPONENTS REFERENCE
+c0=## Per-function overrides: `C0`/`always`
+always-tag=## Per-function overrides: `C0`/`always`
 c1=## C1 — Command Shadows
 command-shadows=## C1 — Command Shadows
 aliases-detail=## C1 — Command Shadows
+filesystem=### filesystem
+network-shadow=### network
+monitor=### monitor
+shell-tools=### shell-tools
+dev-tools=### dev-tools
 c2=## C2 — Startup Side-Effects
 autoexec=## C2 — Startup Side-Effects
 startup=## C2 — Startup Side-Effects
+plugin-management=### plugin-management
+pkg-wrappers=### pkg-wrappers
+venv-toggle=### venv
+telemetry=### telemetry
+sync=### sync
 c3=## C3 — Key and Environment Overrides
 overrides-detail=## C3 — Key and Environment Overrides
 bang-bang=## C3 — Key and Environment Overrides
+bindings-toggle=### key-bindings
+environment=### environment
+prompt-toggle=### prompt
 c4=## C4 — Terminal and Tool Integration
 integrations-detail=## C4 — Terminal and Tool Integration
+terminal-abbrs=### terminal-abbrs
+window-mgmt=### window-mgmt
+window-management=### window-mgmt
+notifications-toggle=### notifications
+history-logs=### history-logs
+pkg-upgrade=### pkg-upgrade
 c5=## C5 — Logging and Capture
 logging-detail=## C5 — Logging and Capture
 logging-sentinel=## C5 — Logging and Capture
@@ -252,11 +318,17 @@ zellij-logging=## C5 — Logging and Capture
 tmux-logging=## C5 — Logging and Capture
 pipe-pane=## C5 — Logging and Capture
 dump-screen=## C5 — Logging and Capture
+terminal-capture=### terminal-capture
+multiplexer-capture=### multiplexer-capture
+pkg-logs=### pkg-logs
 c6=## C6 — Greeting and First-Run UI
 greeting=## C6 — Greeting and First-Run UI
+first-run=### first-run
+greeting-message=### greeting-message
 
 # ── Prompt and Theme ──────────────────────────────────────────
 prompt-theme=## Prompt and Theme
+prompt=## Prompt and Theme
 starship=### Starship
 fallback-prompt=### Catppuccin Fallback Prompt
 catppuccin-prompt=### Catppuccin Fallback Prompt
@@ -316,11 +388,12 @@ minimal-trouble=## What's with the C1-C6 stuff?
 viewing=# 13. VIEWING THIS MANUAL
 manual=# 13. VIEWING THIS MANUAL
 ov=## In the terminal
-man-page=## As a man page
 manpage=## As a man page
 jump=## In the terminal
 html=## The documentation website
 browser=## The documentation website
 site=## The documentation website
+source=## Reading the source directly
+raw-source=## Reading the source directly
 
 
-- 
2.54.0


From 6cf690e63793d503f9fc09ccb2791df01615faa8 Mon Sep 17 00:00:00 2001
From: Rootiest <chris@rootiest.com>
Date: Mon, 31 Aug 2026 22:07:06 -0400
Subject: [PATCH 2/2] fix(help): resolve singular and plural section keywords

The heading scan matches a keyword contained in a heading, so a plural
could never reach a singular heading: `customization` found "7.
CUSTOMIZATION" and `customizations` found nothing at all. The index
lookup was exact-match, so it could not cover the gap either without an
alias per word.

Both now try the keyword as typed first, then its singular/plural
forms. Each variant is tried against every heading before the next one
is considered, so a loose plural cannot beat an exact hit further down
the document.
---
 functions/config-help.fish | 44 ++++++++++++++++++++++++++++++++------
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/functions/config-help.fish b/functions/config-help.fish
index 562874e..f359e4c 100644
--- a/functions/config-help.fish
+++ b/functions/config-help.fish
@@ -77,6 +77,27 @@ function config-help --description 'Open the offline fish shell configuration ma
     if test -n "$section_kw"
         set -l norm_kw (string lower -- $section_kw | string replace -ra '[^a-z0-9]' '')
 
+        # Singular/plural variants of the keyword. The heading scan below
+        # matches a keyword that is *contained in* a heading, so a plural
+        # never reaches a singular heading on its own: `customization`
+        # finds "7. CUSTOMIZATION", `customizations` finds nothing. The
+        # keyword as typed is always tried first and alone; these only run
+        # when it matched nothing at all.
+        set -l kw_variants $norm_kw
+        if test -n "$norm_kw"
+            if string match -qr 's$' -- $norm_kw
+                if string match -qr 'ies$' -- $norm_kw
+                    set -a kw_variants (string replace -r 'ies$' y -- $norm_kw)
+                end
+                if string match -qr 'es$' -- $norm_kw
+                    set -a kw_variants (string replace -r 'es$' '' -- $norm_kw)
+                end
+                set -a kw_variants (string replace -r 's$' '' -- $norm_kw)
+            else
+                set -a kw_variants "$norm_kw"s "$norm_kw"es
+            end
+        end
+
         # 1. Index lookup (keyword aliases)
         if test -f "$idx_file"
             while read -l idxline
@@ -84,7 +105,7 @@ function config-help --description 'Open the offline fish shell configuration ma
                 set -l kv (string split -m 1 '=' -- $idxline)
                 test (count $kv) -lt 2; and continue
                 set -l k (string lower -- $kv[1] | string replace -ra '[^a-z0-9]' '')
-                if test "$k" = "$norm_kw"
+                if contains -- $k $kw_variants
                     set found_text $kv[2]
                     break
                 end
@@ -92,13 +113,22 @@ function config-help --description 'Open the offline fish shell configuration ma
         end
 
         # 2. Normalized heading scan fallback
+        # Each variant is tried against every heading before the next one
+        # is considered, so a loose plural never beats an exact hit that
+        # appears further down the document.
         if test -z "$found_text"; and test -f "$doc_file"
-            for entry in (grep -n "^#" "$doc_file")
-                set -l parts (string split -m 1 ':' -- $entry)
-                set -l text $parts[2]
-                set -l norm_text (string lower -- $text | string replace -ra '[^a-z0-9]' '')
-                if string match -q "*$norm_kw*" $norm_text
-                    set found_text $text
+            set -l heading_lines (grep -n "^#" "$doc_file")
+            for kw in $kw_variants
+                for entry in $heading_lines
+                    set -l parts (string split -m 1 ':' -- $entry)
+                    set -l text $parts[2]
+                    set -l norm_text (string lower -- $text | string replace -ra '[^a-z0-9]' '')
+                    if string match -q "*$kw*" $norm_text
+                        set found_text $text
+                        break
+                    end
+                end
+                if test -n "$found_text"
                     break
                 end
             end
-- 
2.54.0