From 4c8e9c9cdb76a17f11cfda035a16f1f98b324916 Mon Sep 17 00:00:00 2001
From: Michael Brooks <mbrooks@slack-corp.com>
Date: Fri, 15 May 2026 09:53:17 -0700
Subject: [PATCH 1/2] fix: add guardrail test for unescaped markdown in command
 descriptions

The docgen command parses Long descriptions as Go text/template and
renders them as MDX for the docs site. Unescaped { characters break
the Docusaurus build. This adds a test that walks all commands and
validates their descriptions render correctly, catching issues in CI
rather than at release time.
---
 .claude/CLAUDE.md |  4 ++++
 cmd/root_test.go  | 26 ++++++++++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index e391a2ba..ba3e8417 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -229,6 +229,10 @@ Use conventional commit format (feat:, fix:, chore:, etc.) for commit titles.
 5. Run `slack docgen ./docs/reference` to generate docs
 6. Consider adding command alias in `AliasMap` if appropriate
 
+### Command Descriptions and Documentation
+
+Command `Long` descriptions are parsed as Go `text/template` by `docgen` and rendered as MDX for the documentation site. Escape `{` and `[` as `\{` and `\[` in description text to prevent build errors on the docs site. Available template functions: `{{Emoji "name"}}`, `{{LinkText "url"}}`, `{{ToBold "text"}}`.
+
 ### Adding New Dependencies
 
 1. Update `go.mod` with the new module version
diff --git a/cmd/root_test.go b/cmd/root_test.go
index 9ca2b472..5a3b7be8 100644
--- a/cmd/root_test.go
+++ b/cmd/root_test.go
@@ -18,6 +18,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"regexp"
 	"strings"
 	"testing"
 
@@ -290,3 +291,28 @@ func testExecCmd(ctx context.Context, args []string) (string, error) {
 	}
 	return clientsMock.GetCombinedOutput(), nil
 }
+
+func Test_CommandDescriptionsRenderForDocs(t *testing.T) {
+	ctx := slackcontext.MockContext(t.Context())
+	tmp, _ := os.MkdirTemp("", "")
+	_ = os.Chdir(tmp)
+	defer os.RemoveAll(tmp)
+
+	cmd, _ := Init(ctx)
+
+	unescapedBrace := regexp.MustCompile(`[^\\{]\{[^{]`)
+
+	var walk func(*cobra.Command)
+	walk = func(c *cobra.Command) {
+		if c.Long != "" {
+			t.Run(c.CommandPath(), func(t *testing.T) {
+				assert.NotRegexp(t, unescapedBrace, c.Long,
+					"description contains unescaped '{' which breaks the MDX docs site; escape as \\{")
+			})
+		}
+		for _, child := range c.Commands() {
+			walk(child)
+		}
+	}
+	walk(cmd)
+}

From 73258929ed9eb55786e34a25d3d44e9924f96f18 Mon Sep 17 00:00:00 2001
From: Michael Brooks <mbrooks@slack-corp.com>
Date: Fri, 15 May 2026 10:07:35 -0700
Subject: [PATCH 2/2] style: add comment to docs escape regex in test

---
 cmd/root_test.go | 1 +
 1 file changed, 1 insertion(+)

diff --git a/cmd/root_test.go b/cmd/root_test.go
index 5a3b7be8..e1a964dd 100644
--- a/cmd/root_test.go
+++ b/cmd/root_test.go
@@ -300,6 +300,7 @@ func Test_CommandDescriptionsRenderForDocs(t *testing.T) {
 
 	cmd, _ := Init(ctx)
 
+	// Matches a lone { that is not escaped (\{) and not part of a Go template ({{)
 	unescapedBrace := regexp.MustCompile(`[^\\{]\{[^{]`)
 
 	var walk func(*cobra.Command)