From f2be702a158789ecff18fd7c50ce84f677785fa4 Mon Sep 17 00:00:00 2001
From: m1ngsama <contact@m1ng.space>
Date: Thu, 28 May 2026 10:28:02 +0800
Subject: [PATCH] Guard active help surfaces

---
 Makefile                        |  1 +
 docs/CHANGELOG.md               |  3 ++
 tests/test_docs_help_surface.sh | 74 +++++++++++++++++++++++++++++++++
 tnt.1                           | 23 ++++++++--
 4 files changed, 97 insertions(+), 4 deletions(-)
 create mode 100755 tests/test_docs_help_surface.sh

diff --git a/Makefile b/Makefile
index bb1828f..04a54f6 100644
--- a/Makefile
+++ b/Makefile
@@ -126,6 +126,7 @@ unit-test:
 script-test: all
 	@echo "Running script tests..."
 	@cd tests && ./test_cli_options.sh
+	@cd tests && ./test_docs_help_surface.sh
 	@cd tests && ./test_logrotate.sh
 	@cd tests && ./test_message_log_tool.sh
 
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 9a0fe78..7168302 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -37,6 +37,9 @@
   and server survival stay responsive.
 
 ### Changed
+- Updated `tnt(1)` to document the current TUI search and pager keys, and
+  added script coverage to keep active help surfaces free of removed support
+  commands.
 - `make install-systemd` now rewrites the installed unit's `ExecStart` to match
   the selected `PREFIX`/`BINDIR`, so package builds that install to `/usr`
   produce a unit pointing at `/usr/bin/tnt`.
diff --git a/tests/test_docs_help_surface.sh b/tests/test_docs_help_surface.sh
new file mode 100755
index 0000000..6d768d3
--- /dev/null
+++ b/tests/test_docs_help_surface.sh
@@ -0,0 +1,74 @@
+#!/bin/sh
+# Regression checks for active help/manual surfaces.
+
+PASS=0
+FAIL=0
+
+pass() {
+    echo "✓ $1"
+    PASS=$((PASS + 1))
+}
+
+fail() {
+    echo "✗ $1"
+    if [ -n "$2" ]; then
+        printf '%s\n' "$2"
+    fi
+    FAIL=$((FAIL + 1))
+}
+
+require_fixed() {
+    file="$1"
+    text="$2"
+    label="$3"
+
+    if grep -F -q "$text" "../$file"; then
+        pass "$label"
+    else
+        fail "$label missing" "$file: $text"
+    fi
+}
+
+forbid_fixed() {
+    file="$1"
+    text="$2"
+    label="$3"
+
+    if grep -F -q "$text" "../$file"; then
+        fail "$label still mentions $text" "$file"
+    else
+        pass "$label excludes $text"
+    fi
+}
+
+echo "=== TNT Help Surface Tests ==="
+
+require_fixed "tnt.1" "/	Search message history" "manual documents NORMAL search"
+require_fixed "tnt.1" "Space/b	Scroll full page down/up" "manual documents space/b paging"
+require_fixed "tnt.1" "PageDown/PageUp	Scroll full page down/up" "manual documents page keys"
+require_fixed "tnt.1" "End/Home	Jump to bottom/top" "manual documents end/home"
+require_fixed "tnt.1" "g/G	Jump to top/bottom" "manual documents g/G"
+require_fixed "tnt.1" ":lang	Show current UI language" "manual documents current language"
+require_fixed "tnt.1" ":lang \fIen|zh\fR	Switch UI language for this session" "manual documents language codes"
+
+for file in \
+    README.md \
+    docs/EASY_SETUP.md \
+    docs/DEPLOYMENT.md \
+    docs/INTERFACE.md \
+    docs/QUICKREF.md \
+    docs/USER_LIFECYCLE.md \
+    tnt.1 \
+    tntctl.1 \
+    src/command_catalog.c \
+    src/help_text.c \
+    src/manual_text.c
+do
+    forbid_fixed "$file" ":support" "$file"
+done
+
+echo ""
+echo "PASSED: $PASS"
+echo "FAILED: $FAIL"
+[ "$FAIL" -eq 0 ] && echo "All tests passed" || echo "Some tests failed"
+exit "$FAIL"
diff --git a/tnt.1 b/tnt.1
index 3befbc9..62f740e 100644
--- a/tnt.1
+++ b/tnt.1
@@ -167,6 +167,8 @@ Press
 to return to INSERT,
 .B :
 to enter COMMAND mode,
+.B /
+to search message history,
 .B ?
 to open the full key reference.
 .TP
@@ -198,6 +200,7 @@ Ctrl+F/Ctrl+B	Scroll full page down/up
 PageDown/PageUp	Scroll full page down/up
 End/Home	Jump to bottom/top
 g/G	Jump to top/bottom
+/	Search message history
 i	Switch to INSERT
 :	Enter COMMAND mode
 ?	Open full key reference
@@ -219,6 +222,7 @@ l l.
 :last [\fIN\fR]	Show last N messages from history (1\-50, default 10)
 :search \fIkeyword\fR	Case\-insensitive search across full message history
 :mute\-joins	Toggle join/leave system notifications on/off
+:lang	Show current UI language
 :lang \fIen|zh\fR	Switch UI language for this session
 :help	Show concise manual
 :clear	Clear command output
@@ -227,12 +231,23 @@ Up/Down	Browse command history
 ESC	Cancel and return to NORMAL
 .TE
 .PP
-Command output pages use j/k, Ctrl+D/Ctrl+U, and g/G for paging.
+Command output pages use the same paging keys as the help screen.
+.TS
+l l.
+q, ESC	Close output
+j/k, arrows	Scroll down/up
+Ctrl+D/Ctrl+U	Scroll half page down/up
+Ctrl+F/Ctrl+B	Scroll full page down/up
+Space/b	Scroll full page down/up
+PageDown/PageUp	Scroll full page down/up
+End/Home	Jump to bottom/top
+g/G	Jump to top/bottom
+r	Refresh live output (:inbox)
+.TE
+.PP
 The
 .B :inbox
-page can also be refreshed with
-.B r
-and refreshes automatically when a new private message arrives while it is
+page refreshes automatically when a new private message arrives while it is
 open.
 .SH EXEC INTERFACE
 Commands can be run non\-interactively for scripting: