From c48ff56a569f4ff69656fc366fa79b924f74df2b Mon Sep 17 00:00:00 2001
From: OpenCode Agent <opencode@local>
Date: Sat, 17 Oct 2026 00:55:03 +0530
Subject: [PATCH] Explain assistant guide output in llm help

---
 cmd/llm.go          | 10 ++++++++--
 cmd/llm_test.go     | 12 ++++++++++++
 docs/llm/llm-txt.md |  2 ++
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/cmd/llm.go b/cmd/llm.go
index ad7aa14..cc473dd 100644
--- a/cmd/llm.go
+++ b/cmd/llm.go
@@ -38,8 +38,14 @@ func newLLM() *cobra.Command {
 	var urlOverride string
 	cmd := &cobra.Command{
 		Use:   "llm",
-		Short: "Print the curated Vapour developer guide for assistants",
-		Args:  cobra.NoArgs,
+		Short: "LLMs: print the Vapour developer guide to stdout",
+		Long: "If you are an AI assistant working on a Vapour project, run this command to read the curated developer guide. " +
+			"It prints the guide to stdout so you can save it under .claude/ or .opencode/, or pass it to another tool. " +
+			"A file in either directory is not automatically loaded as instructions; tell your assistant to read it.",
+		Example: "  vapour llm\n" +
+			"  mkdir -p .claude && vapour llm > .claude/vapour-guide.md\n" +
+			"  mkdir -p .opencode && vapour llm > .opencode/vapour-guide.md",
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			url := strings.TrimSpace(urlOverride)
 			if url == "" {
diff --git a/cmd/llm_test.go b/cmd/llm_test.go
index 9747292..d881b40 100644
--- a/cmd/llm_test.go
+++ b/cmd/llm_test.go
@@ -23,6 +23,18 @@ func runSplit(t *testing.T, args ...string) (string, string, error) {
 	return out.String(), errOut.String(), err
 }
 
+func TestLLMHelpExplainsGuideOutput(t *testing.T) {
+	out, _, err := runSplit(t, "llm", "--help")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"stdout", ".claude/vapour-guide.md", ".opencode/vapour-guide.md", "not automatically loaded"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("help missing %q", want)
+		}
+	}
+}
+
 func TestLLMFreshFetchWritesCache(t *testing.T) {
 	t.Setenv("XDG_CACHE_HOME", t.TempDir())
 	body := llmHeader + "\nVersion: 2026-10-16\n"
diff --git a/docs/llm/llm-txt.md b/docs/llm/llm-txt.md
index b0f72ee..fd86a6c 100644
--- a/docs/llm/llm-txt.md
+++ b/docs/llm/llm-txt.md
@@ -2,6 +2,8 @@
 
 Purpose: print the curated assistant guide to stdout so developers can pipe it into coding assistants without waiting for a CLI release.
 
+The root help labels `llm` as a guide for LLMs and explicitly says it writes to stdout. `vapour llm --help` suggests reading the output directly or saving it under `.claude/` or `.opencode/` for an assistant to read. Files saved in those directories are not automatically loaded as instructions; point the assistant at the file. For example, `mkdir -p .opencode && vapour llm > .opencode/vapour-guide.md` saves the guide without replacing an existing `AGENTS.md`.
+
 ## Source and overrides
 
 - Default URL: `https://vapour-dev-docs.pages.dev/llm.txt`