From f376372630a7a765150b3fcc40825e2615d2c56e Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Thu, 2 Apr 2026 05:43:29 +0000
Subject: [PATCH] feat(help): show suggestions for missing topics

---
 cmd/core/help/cmd.go      |  6 ++++++
 cmd/core/help/cmd_test.go | 26 ++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/cmd/core/help/cmd.go b/cmd/core/help/cmd.go
index 82f9635..0ddda7d 100644
--- a/cmd/core/help/cmd.go
+++ b/cmd/core/help/cmd.go
@@ -33,6 +33,12 @@ func AddHelpCommands(root *cli.Command) {
 
 			topic, err := catalog.Get(args[0])
 			if err != nil {
+				if suggestions := catalog.Search(args[0]); len(suggestions) > 0 {
+					if suggestErr := renderSearchResults(suggestions, args[0]); suggestErr != nil {
+						return suggestErr
+					}
+					cli.Blank()
+				}
 				return cli.Err("help topic %q not found", args[0])
 			}
 
diff --git a/cmd/core/help/cmd_test.go b/cmd/core/help/cmd_test.go
index aa72e63..6cabe44 100644
--- a/cmd/core/help/cmd_test.go
+++ b/cmd/core/help/cmd_test.go
@@ -135,4 +135,30 @@ func TestAddHelpCommands_Bad(t *testing.T) {
 		require.Error(t, err)
 		assert.Contains(t, err.Error(), "help topic")
 	})
+
+	t.Run("missing topic shows suggestions when available", func(t *testing.T) {
+		catalog := gohelp.DefaultCatalog()
+		query := ""
+		for _, candidate := range []string{"configuration", "docs", "search", "topic", "help"} {
+			if _, err := catalog.Get(candidate); err == nil {
+				continue
+			}
+			if len(catalog.Search(candidate)) > 0 {
+				query = candidate
+				break
+			}
+		}
+		if query == "" {
+			t.Skip("no suitable query found with suggestions")
+		}
+
+		cmd := newHelpCommand(t)
+		out := captureOutput(t, func() {
+			err := cmd.RunE(cmd, []string{query})
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), "help topic")
+		})
+
+		assert.Contains(t, out, "SEARCH RESULTS")
+	})
 }