Merge pull request 'feat(docs): offline documentation, config_help viewer, and CI pipelines' (#32) from feat/offline-documentation into main

Reviewed-on: #32

.gitea/workflows/docs-drift.yml

@@ -0,0 +1,45 @@
+name: Offline docs drift reminder
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'README.md'
+
+jobs:
+  remind:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Check whether offline doc changed in same push
+        id: drift
+        run: |
+          if git diff --name-only HEAD~1 HEAD | grep -q '^docs/fish-config\.md$'; then
+            echo "synced=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "synced=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Open drift reminder issue
+        if: steps.drift.outputs.synced == 'false'
+        uses: actions/gitea-issue-create@v1
+        with:
+          token: ${{ secrets.GITEA_TOKEN }}
+          title: "docs: README updated — review docs/fish-config.md for drift"
+          body: |
+            README.md was modified in commit ${{ github.sha }} but
+            `docs/fish-config.md` (the offline manual) was not updated in
+            the same push.
+
+            Please review the README diff and update the offline documentation
+            if any functions, keybindings, abbreviations, or configuration
+            options were added, removed, or changed.
+
+            Commit: ${{ github.sha }}
+            Branch: ${{ github.ref_name }}
+          labels: documentation

.gitea/workflows/man-page.yml

@@ -0,0 +1,37 @@
+name: Generate man page
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/fish-config.md'
+
+jobs:
+  build-manpage:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITEA_TOKEN }}
+
+      - name: Install pandoc
+        run: sudo apt-get update -qq && sudo apt-get install -y pandoc
+
+      - name: Compile man page
+        run: |
+          pandoc --standalone \
+                 --from markdown \
+                 --to man \
+                 docs/fish-config.md \
+                 -o docs/fish-config.1
+
+      - name: Commit man page
+        run: |
+          git config user.name  "Gitea Actions"
+          git config user.email "actions@gitea"
+          git add docs/fish-config.1
+          git diff --cached --quiet && echo "No changes to commit" && exit 0
+          git commit -m "chore(docs): regenerate fish-config.1 man page"
+          git push

README.md

@@ -305,6 +305,19 @@ rm -f file.txt  # Falls through to standard rm -f
 
 `conf.d/paru-wrapper.fish` and `conf.d/yay-wrapper.fish` auto-generate thin wrapper scripts at `~/.local/bin/paru` and `~/.local/bin/yay` on first shell start (when the respective AUR helper is installed). These wrappers tee all output to timestamped log files in `SCROLLBACK_HISTORY_DIR` and prune old logs to stay under `SCROLLBACK_HISTORY_MAX_FILES`.
 
+### Offline Documentation
+
+A curated offline reference manual is available at `docs/fish-config.md`. It covers every function, keybinding, abbreviation, and configuration variable, written for terminal readability (no hyperlinks or GitHub-specific callouts).
+
+| Command | Description |
+|---|---|
+| `config_help` | Open the offline manual in the best available pager |
+| `config_help <keyword>` | Jump directly to a section matching the keyword |
+
+The viewer falls back through: **ov** (syntax highlight + section navigation) → **bat** (syntax highlight) → **man -l** (pre-compiled man page) → **less** → **cat**.
+
+Examples: `config_help keybindings` · `config_help pkg` · `config_help fish-deps` · `config_help abbreviations`
+
 ### Dependency Management
 
 `fish-deps` is a unified command for checking, installing, and updating all tools this config depends on.

docs/fish-config.index

@@ -0,0 +1,176 @@
+# Fish Config Help Index
+# Format: keyword=exact heading text as it appears in fish-config.md
+# Multiple keywords may map to the same heading.
+# Update this file whenever headings are added, removed, or renamed.
+# config_help uses this for fast exact lookups; unknown keywords fall back
+# to a normalized heading scan automatically.
+
+# ── Top-level ─────────────────────────────────────────────────
+name=# NAME
+synopsis=# SYNOPSIS
+description=# DESCRIPTION
+toc=# TABLE OF CONTENTS
+contents=# TABLE OF CONTENTS
+
+# ── Section 1: Configuration Variables ───────────────────────
+variables=# 1. CONFIGURATION VARIABLES
+config=# 1. CONFIGURATION VARIABLES
+xdg=## Environment Directories (XDG)
+toolhomes=## Tool Homes (XDG-compliant)
+editor=## Editor and Pager
+pager=## Editor and Pager
+scrollback=## Scrollback History
+
+# ── Section 2: PATH ───────────────────────────────────────────
+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 (from fzf --fish integration)
+fzf=## FZF Bindings (from fzf --fish integration)
+
+# ── Section 4: Abbreviations ──────────────────────────────────
+abbreviations=# 4. ABBREVIATIONS
+abbr=# 4. ABBREVIATIONS
+abbrs=# 4. ABBREVIATIONS
+editors-abbr=## 4.1 Editors
+nav=## 4.2 Navigation and Listing
+navigation=## 4.2 Navigation and Listing
+listing=## 4.2 Navigation and Listing
+git-abbr=## 4.3 Git
+terminal=## 4.4 Terminal Windows, Tabs, and Panes
+panes=## 4.4 Terminal Windows, Tabs, and Panes
+windows=## 4.4 Terminal Windows, Tabs, and Panes
+tabs=## 4.4 Terminal Windows, Tabs, and Panes
+chezmoi=## 4.5 Chezmoi
+docker=## 4.6 Docker
+systemctl=## 4.7 Systemctl
+systemd=## 4.7 Systemctl
+ai-abbr=## 4.8 AI Assistants
+history=## 4.9 History Expansion
+misc-abbr=## 4.10 Miscellaneous
+
+# ── Section 5: Functions ──────────────────────────────────────
+functions=# 5. FUNCTIONS REFERENCE
+files=## 5.1 File and Directory
+cat=### cat
+copy=### copy
+du=### du
+dusize=### dusize
+ls=### ls
+lsr=### lsr
+lss=### lss
+lstree=### lstree
+lt=### lt
+ltr=### ltr
+lx=### lx
+mkdir=### mkdir
+mkcd=### mkcd
+poke=### poke
+rm=### rm
+scrub=### scrub
+nav-fns=## 5.2 Navigation
+cdi=### cdi
+clone=### clone
+clonet=### clonet
+editors=## 5.3 Editors and Viewers
+edit=### edit
+fc=### fc
+less=### less
+rawfish=### rawfish
+view=### view
+git=## 5.4 Git and Version Control
+branch=### branch
+gi=### gi
+gitignore=### gi
+git-clean=### git-clean
+gitup=### gitup
+gitui=### gitui
+hist=### hist
+pkg=### pkg
+package=### pkg
+package-manager=## 5.5 Package Management
+packages=## 5.5 Package Management
+search=### search
+upgrade=### upgrade
+cleanup=### cleanup
+parur=### parur
+deps=## 5.6 Dependency Management
+fish-deps=### fish-deps
+check-deps=### check_fish_deps
+system=## 5.7 System and Monitoring
+top=### top
+swapstat=### swapstat
+sbver=### sbver
+ports=### ports
+screensleep=### screensleep
+lock=### lock
+sudo-toggle=### sudo-toggle
+limine=### limine-edit
+terminal-mgmt=## 5.8 Terminal Management
+tab=### tab
+split=### split
+spwin=### spwin
+detach=### detach
+bkg=### bkg
+ssh=### ssh
+clipboard=## 5.9 Clipboard
+copy-fn=### y
+paste=### paste
+network=## 5.10 Network
+gip=### gip
+ping=### ping
+qr=### qr
+logging=## 5.11 Pager and Logging
+logs=### logs
+smart-exit=### smart_exit
+ai=## 5.12 AI and Developer Tools
+antigravity=### antigravity
+claude=### claude-resume
+claude-docs=### claude-docs
+claude-pr=### claude-pr
+code-resume=### code-resume
+superpowers=### superpowers
+media=## 5.13 Media and Utilities
+dng2avif=### dng2avif
+spark=### spark
+miscfns=## 5.14 Miscellaneous
+bash=### bash
+cheat=### cheat
+dockup=### dockup
+joplin=### joplin
+replay=### replay
+tmux=### tmux-clean
+wake-lock=### wake-lock
+zellij=### zellij
+
+# ── Section 6: Dependency Catalog ────────────────────────────
+catalog=# 6. DEPENDENCY CATALOG
+deps-catalog=# 6. DEPENDENCY CATALOG
+required=## Required
+integrations=## Integrations
+recommended=## Recommended
+install-methods=## Install Methods
+
+# ── Section 7: Customization ──────────────────────────────────
+customization=# 7. CUSTOMIZATION
+customize=# 7. CUSTOMIZATION
+local=## Machine-local Configuration
+secrets=## Secrets and API Keys
+overrides=## Overriding Configuration Variables
+universal=## Fish Universal Variables
+
+# ── Section 8: Fisher Plugins ─────────────────────────────────
+plugins=# 8. FISHER PLUGINS
+fisher=# 8. FISHER PLUGINS
+
+# ── Section 9: Viewing This Manual ───────────────────────────
+viewing=# 9. VIEWING THIS MANUAL
+manual=# 9. VIEWING THIS MANUAL
+ov=## With ov (recommended)
+man-page=## As a man page (if compiled)
+manpage=## As a man page (if compiled)
+jump=## Jumping to a section

functions/config_help.fish

@@ -0,0 +1,212 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# SYNOPSIS
+#   config_help [section]
+#   config_help --help
+#
+# DESCRIPTION
+#   Opens the offline fish shell configuration manual in the best available
+#   pager. Falls back through ov -> bat -> man -> less -> cat.
+#   If a section keyword is provided, the pager opens at the first heading
+#   that matches the keyword. Lookup order: docs/fish-config.index (exact
+#   keyword aliases), then a normalized heading scan as fallback.
+#   When opened with ov a sticky navigation hint is shown at the top of the
+#   screen. Pass --help or -h to print usage and navigation key reference.
+#
+# ARGUMENTS
+#   section   Optional keyword to jump to a matching section heading
+#   --help    Print usage and navigation reference, then exit
+#   -h        Alias for --help
+#
+# RETURNS
+#   0  Manual displayed (or --help printed)
+#   1  Documentation file not found
+#
+# EXAMPLE
+#   config_help
+#   config_help keybindings
+#   config_help pkg
+#   config_help fish-deps
+#   config_help --help
+function config_help --description 'Open the offline fish shell configuration manual'
+    # ── --help / -h ──────────────────────────────────────────────
+    if contains -- --help $argv; or contains -- -h $argv
+        set_color --bold
+        echo config_help
+        set_color normal
+        echo " — view the offline fish shell configuration manual"
+        echo ""
+        set_color --bold brblue
+        echo USAGE
+        set_color normal
+        echo "  config_help "(set_color yellow)"[section]"(set_color normal)
+        echo "  config_help "(set_color yellow)"--help"(set_color normal)
+        echo ""
+        set_color --bold brblue
+        echo ARGUMENTS
+        set_color normal
+        echo "  "(set_color yellow)"section"(set_color normal)"   Optional keyword to jump to a matching section heading."
+        echo "            Searches docs/fish-config.index for aliases first, then"
+        echo "            falls back to a normalized (case- and punctuation-insensitive)"
+        echo "            scan of heading lines."
+        echo ""
+        set_color --bold brblue
+        echo EXAMPLES
+        set_color normal
+        echo "  "(set_color green)"config_help"(set_color normal)"                  open at top"
+        echo "  "(set_color green)"config_help keybindings"(set_color normal)"      jump to Key Bindings section"
+        echo "  "(set_color green)"config_help pkg"(set_color normal)"              jump to the pkg function entry"
+        echo "  "(set_color green)"config_help fish-deps"(set_color normal)"        jump to fish-deps"
+        echo "  "(set_color green)"config_help abbreviations"(set_color normal)"    jump to Abbreviations section"
+        echo ""
+        set_color --bold brblue
+        echo "NAVIGATION (ov pager)"
+        set_color normal
+        echo "  "(set_color cyan)"Space"(set_color normal)"       next section"
+        echo "  "(set_color cyan)"^"(set_color normal)"           previous section"
+        echo "  "(set_color cyan)"Alt+u"(set_color normal)"       toggle section list sidebar"
+        echo "  "(set_color cyan)"/"(set_color normal)"           search forward"
+        echo "  "(set_color cyan)"n"(set_color normal)" / "(set_color cyan)"N"(set_color normal)"       next / previous search match"
+        echo "  "(set_color cyan)"g"(set_color normal)"           go to line number"
+        echo "  "(set_color cyan)"q"(set_color normal)"           quit"
+        echo ""
+        set_color --bold brblue
+        echo "PAGER FALLBACK CHAIN"
+        set_color normal
+        echo "  "(set_color brblack)"1."(set_color normal)" ov + bat   section nav + syntax highlighting  "(set_color brblack)"(best)"(set_color normal)
+        echo "  "(set_color brblack)"2."(set_color normal)" ov alone   section nav, raw Markdown"
+        echo "  "(set_color brblack)"3."(set_color normal)" bat alone  syntax highlighting, use / to search"
+        echo "  "(set_color brblack)"4."(set_color normal)" man -l     pre-compiled man page (if available)"
+        echo "  "(set_color brblack)"5."(set_color normal)" less       plain text with line-jump"
+        echo "  "(set_color brblack)"6."(set_color normal)" cat        plain output"
+        return 0
+    end
+
+    set -l doc_file "$__fish_config_dir/docs/fish-config.md"
+    set -l idx_file "$__fish_config_dir/docs/fish-config.index"
+    set -l man_file "$__fish_config_dir/docs/fish-config.1"
+
+    if not test -f "$doc_file"
+        set_color red
+        echo "error: documentation not found at $doc_file" >&2
+        set_color normal
+        return 1
+    end
+
+    # ── Resolve section start line ───────────────────────────────
+    # 1. Look up keyword in fish-config.index (keyword → exact heading text).
+    # 2. Fall back to normalized scan of heading lines if not in index.
+    # 3. Resolve start_line via grep -F on the heading text (immune to line
+    #    number drift — only breaks if the heading itself is renamed).
+    set -l start_line 1
+    if test -n "$argv[1]"
+        set -l norm_kw (string lower -- $argv[1] | string replace -ra '[^a-z0-9]' '')
+        set -l found_text ""
+
+        # ── Index lookup ─────────────────────────────────────────
+        if test -f "$idx_file"
+            while read -l idxline
+                string match -qr '^[[:space:]]*(#|$)' -- $idxline; and continue
+                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"
+                    set found_text $kv[2]
+                    break
+                end
+            end <"$idx_file"
+        end
+
+        # ── Normalized scan fallback ─────────────────────────────
+        if test -z "$found_text"
+            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
+                    break
+                end
+            end
+        end
+
+        if test -n "$found_text"
+            set -l lnum (grep -Fn "$found_text" "$doc_file" | cut -d: -f1 | head -1)
+            if test -n "$lnum"
+                set start_line $lnum
+            end
+        else
+            set_color yellow
+            echo "note: no section matching '$argv[1]' — opening at top" >&2
+            set_color normal
+        end
+    end
+
+    # ── Navigation hint line ─────────────────────────────────────
+    # Prepended to the ov input stream and pinned via --header 1 so it
+    # remains visible at the top of the screen at all times.
+    set -l nav_hint \
+        " \033[2mNAVIGATION: [ Space=next section  ^=prev  Alt+u=sections  /=search  q=quit ]\033[0m"
+
+    # ── Viewer fallback chain ────────────────────────────────────
+    # When jumping to a section, slice the file from start_line so ov
+    # opens with that section at the top without needing --pattern.
+    # (--section-header pins delimiter lines as sticky headers, removing
+    # them from pattern-search scope — tail-slice sidesteps this entirely.)
+    if type -q ov; and type -q bat
+        set -l ov_args \
+            --header 1 \
+            --section-delimiter "^#" \
+            --section-header
+        if test $start_line -gt 1
+            begin
+                printf "$nav_hint\n"
+                bat --color=always --style=plain --language=markdown "$doc_file" \
+                    | tail -n +$start_line
+            end | ov $ov_args
+        else
+            begin
+                printf "$nav_hint\n"
+                bat --color=always --style=plain --language=markdown "$doc_file"
+            end | ov $ov_args
+        end
+
+        # ov alone: section navigation on raw Markdown; no code highlighting.
+    else if type -q ov
+        set -l ov_args \
+            --header 1 \
+            --section-delimiter "^#" \
+            --section-header
+        if test $start_line -gt 1
+            begin
+                printf "$nav_hint\n"
+                tail -n +$start_line "$doc_file"
+            end | ov $ov_args
+        else
+            begin
+                printf "$nav_hint\n"
+                cat "$doc_file"
+            end | ov $ov_args
+        end
+
+        # bat alone: syntax highlighting with built-in paging; no line jump.
+    else if type -q bat
+        if test $start_line -gt 1
+            set_color brblack
+            echo "note: bat pager — use / to search for your section" >&2
+            set_color normal
+        end
+        bat --language=markdown --paging=always "$doc_file"
+
+        # Pre-compiled man page (generated by CI after merge).
+    else if test -f "$man_file"
+        man -l "$man_file"
+
+    else if type -q less
+        less +"$start_line" "$doc_file"
+
+    else
+        cat "$doc_file"
+    end
+end