.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.

functions/config_help.fish

@@ -0,0 +1,75 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# SYNOPSIS
+#   config_help [section]
+#
+# 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 (case-insensitive).
+#
+# ARGUMENTS
+#   section  Optional keyword to jump to a matching section heading
+#
+# RETURNS
+#   0  Manual displayed
+#   1  Documentation file not found
+#
+# EXAMPLE
+#   config_help
+#   config_help keybindings
+#   config_help pkg
+#   config_help fish-deps
+function config_help --description 'Open the offline fish shell configuration manual'
+    set -l doc_file "$__fish_config_dir/docs/fish-config.md"
+    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 ───────────────────────────────
+    set -l start_line 1
+    if test -n "$argv[1]"
+        set -l found (grep -n -im 1 "^#\+.*$argv[1]" "$doc_file" | cut -d: -f1)
+        if test -n "$found"
+            set start_line $found
+        else
+            set_color yellow
+            echo "note: no section matching '$argv[1]' — opening at top" >&2
+            set_color normal
+        end
+    end
+
+    # ── Viewer fallback chain ────────────────────────────────────
+    if type -q ov
+        ov --syntax --syntax-name markdown \
+           --section-delimiter "^#" \
+           --section-header \
+           +"$start_line" "$doc_file"
+
+    else if type -q bat
+        if test $start_line -gt 1
+            # bat can't jump to a line in paging mode; show a hint instead
+            set_color brblack
+            echo "note: bat pager active — use / to search for your section" >&2
+            set_color normal
+        end
+        bat --language=markdown --paging=always "$doc_file"
+
+    else if test -f "$man_file"
+        # Pre-compiled man page as a pager-independent fallback
+        man -l "$man_file"
+
+    else if type -q less
+        less +"$start_line" "$doc_file"
+
+    else
+        cat "$doc_file"
+    end
+end