From 181d9546b40d3ce095416423d2037f45141bcf2f Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Thu, 2 Apr 2026 04:51:19 +0000
Subject: [PATCH] feat(help): show topic previews

Co-Authored-By: Virgil <virgil@lethean.io>
---
 cmd/core/help/cmd.go      | 25 +++++++++++++++++++++++++
 cmd/core/help/cmd_test.go | 17 +++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/cmd/core/help/cmd.go b/cmd/core/help/cmd.go
index 67c9a72..2c2bf9e 100644
--- a/cmd/core/help/cmd.go
+++ b/cmd/core/help/cmd.go
@@ -1,6 +1,7 @@
 package help
 
 import (
+	"bufio"
 	"strings"
 
 	"forge.lthn.ai/core/cli/pkg/cli"
@@ -63,10 +64,34 @@ func renderTopicList(topics []*gohelp.Topic) error {
 	cli.Section("Available Help Topics")
 	for _, topic := range topics {
 		cli.Println("  %s - %s", topic.ID, topic.Title)
+		if summary := topicSummary(topic); summary != "" {
+			cli.Println("%s", cli.DimStr("    "+summary))
+		}
 	}
 	return nil
 }
 
+func topicSummary(topic *gohelp.Topic) string {
+	if topic == nil {
+		return ""
+	}
+
+	content := strings.TrimSpace(topic.Content)
+	if content == "" {
+		return ""
+	}
+
+	scanner := bufio.NewScanner(strings.NewReader(content))
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		return line
+	}
+	return ""
+}
+
 func renderTopic(t *gohelp.Topic) {
 	cli.Blank()
 	cli.Println("%s", cli.TitleStyle.Render(t.Title))
diff --git a/cmd/core/help/cmd_test.go b/cmd/core/help/cmd_test.go
index 91ef803..1d65d83 100644
--- a/cmd/core/help/cmd_test.go
+++ b/cmd/core/help/cmd_test.go
@@ -78,6 +78,23 @@ func TestRenderSearchResults_Good(t *testing.T) {
 	assert.Contains(t, out, "Core is configured via environment variables.")
 }
 
+func TestRenderTopicList_Good(t *testing.T) {
+	out := captureOutput(t, func() {
+		err := renderTopicList([]*gohelp.Topic{
+			{
+				ID:      "config",
+				Title:   "Configuration",
+				Content: "# Configuration\n\nCore is configured via environment variables.\n\nMore details follow.",
+			},
+		})
+		require.NoError(t, err)
+	})
+
+	assert.Contains(t, out, "AVAILABLE HELP TOPICS")
+	assert.Contains(t, out, "config - Configuration")
+	assert.Contains(t, out, "Core is configured via environment variables.")
+}
+
 func TestAddHelpCommands_Bad(t *testing.T) {
 	t.Run("missing search results", func(t *testing.T) {
 		cmd := newHelpCommand(t)
-- 
2.45.3