Merge pull request 'fix(help): full index audit and singular/plural keyword matching' (#122) from docs/index-full-audit into main

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
+rand_string=### rand_string
-config-settings=### config-settings
+random=### rand_string
-config-toggle=### config-settings
+password=### rand_string
-toggle=### config-settings
+randomword=### rand_string
-bash=### bash
-cheat=### cheat
-dockup=### dockup
-joplin=### joplin
 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
 
 

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,16 +113,25 @@ 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 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 "*$norm_kw*" $norm_text
+                    if string match -q "*$kw*" $norm_text
                         set found_text $text
                         break
                     end
                 end
+                if test -n "$found_text"
+                    break
+                end
+            end
         end
     end