cmd/core/help/cmd.go

@@ -2,6 +2,7 @@ package help
 
 import (
 	"bufio"
+	"fmt"
 	"strings"
 
 	"forge.lthn.ai/core/cli/pkg/cli"
@@ -38,7 +39,10 @@ func AddHelpCommands(root *cli.Command) {
 						return suggestErr
 					}
 					cli.Blank()
+					renderHelpHint(args[0])
+					return cli.Err("help topic %q not found", args[0])
 				}
+				renderHelpHint(args[0])
 				return cli.Err("help topic %q not found", args[0])
 			}
 
@@ -89,6 +93,7 @@ func searchHelpTopics(catalog *gohelp.Catalog, query string) error {
 
 func renderSearchResults(results []*gohelp.SearchResult, query string) error {
 	if len(results) == 0 {
+		renderHelpHint(query)
 		return cli.Err("no help topics matched %q", query)
 	}
 
@@ -102,6 +107,13 @@ func renderSearchResults(results []*gohelp.SearchResult, query string) error {
 	return nil
 }
 
+func renderHelpHint(query string) {
+	cli.Hint("browse", "core help")
+	if trimmed := strings.TrimSpace(query); trimmed != "" {
+		cli.Hint("search", fmt.Sprintf("core help search %q", trimmed))
+	}
+}
+
 func renderTopicList(topics []*gohelp.Topic) error {
 	if len(topics) == 0 {
 		return cli.Err("no help topics available")

cmd/core/help/cmd_test.go

@@ -161,9 +161,28 @@ func TestAddHelpCommands_Bad(t *testing.T) {
 		cmd := newHelpCommand(t)
 		require.NoError(t, cmd.Flags().Set("search", "zzzyyyxxx"))
 
-		err := cmd.RunE(cmd, nil)
-		require.Error(t, err)
-		assert.Contains(t, err.Error(), "no help topics matched")
+		out := captureOutput(t, func() {
+			err := cmd.RunE(cmd, nil)
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), "no help topics matched")
+		})
+
+		assert.Contains(t, out, "browse")
+		assert.Contains(t, out, "core help")
+		assert.Contains(t, out, "core help search")
+	})
+
+	t.Run("missing topic without suggestions shows hints", func(t *testing.T) {
+		cmd := newHelpCommand(t)
+
+		out := captureOutput(t, func() {
+			err := cmd.RunE(cmd, []string{"definitely-not-a-real-topic"})
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), "help topic")
+		})
+
+		assert.Contains(t, out, "browse")
+		assert.Contains(t, out, "core help")
 	})
 
 	t.Run("missing search query", func(t *testing.T) {
@@ -179,13 +198,6 @@ func TestAddHelpCommands_Bad(t *testing.T) {
 		assert.Contains(t, err.Error(), "help search query is required")
 	})
 
-	t.Run("missing topic", func(t *testing.T) {
-		cmd := newHelpCommand(t)
-		err := cmd.RunE(cmd, []string{"definitely-not-a-real-topic"})
-		require.Error(t, err)
-		assert.Contains(t, err.Error(), "help topic")
-	})
-
 	t.Run("missing topic shows suggestions when available", func(t *testing.T) {
 		query := searchableHelpQuery(t)