feat(commands): improve discovery and normalize parameters

internal/modules/coin/coin.go

@@ -15,24 +15,32 @@ func New(deps modules.Deps) modules.Module {
 				Name:        "coin_price",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Show current crypto price in USD",
+				Parameters:  "<coin>",
+				Example:     "/coin_price BTC",
 				Handler:     s.handlePrice,
 			},
 			{
 				Name:        "coin_topup",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Top up USD to your coin account",
+				Parameters:  "<usd_amount>",
+				Example:     "/coin_topup 1000",
 				Handler:     s.handleTopup,
 			},
 			{
 				Name:        "coin_buy",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Spend a USD amount to buy coin",
+				Parameters:  "<coin> <usd_to_spend>",
+				Example:     "/coin_buy BTC 10",
 				Handler:     s.handleBuy,
 			},
 			{
 				Name:        "coin_sell",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Sell enough coin to receive a USD amount",
+				Parameters:  "<coin> <usd_to_receive>",
+				Example:     "/coin_sell BTC 10",
 				Handler:     s.handleSell,
 			},
 			{

internal/modules/coin/handlers.go

@@ -20,7 +20,7 @@ var (
 func (s *state) handlePrice(ctx context.Context, b *bot.Bot, update *models.Update) error {
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 1 {
-		return chathelper.Reply(ctx, b, update.Message, "Usage: /coin_price <COIN>\nExample: /coin_price BTC")
+		return chathelper.Reply(ctx, b, update.Message, "Usage: /coin_price <coin>\nExample: /coin_price BTC")
 	}
 	coin, err := ResolveCoinSymbol(args[0])
 	if err != nil {
@@ -70,7 +70,7 @@ func (s *state) handleBuy(ctx context.Context, b *bot.Bot, update *models.Update
 	}
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 2 {
-		return chathelper.Reply(ctx, b, update.Message, "Usage: /coin_buy <COIN> <usd_amount>\nSpend USD to buy coin.\nAlternative: /coin_buy <usd_amount> <COIN>\nExample: /coin_buy BTC 10")
+		return chathelper.Reply(ctx, b, update.Message, "Usage: /coin_buy <coin> <usd_to_spend>\nSpend USD to buy coin.\nAlternative: /coin_buy <usd_to_spend> <coin>\nExample: /coin_buy BTC 10")
 	}
 	parsed, err := parseCoinValueArgs(args, isSafeUSD, errInvalidUSDAmount)
 	if errors.Is(err, errInvalidUSDAmount) {
@@ -124,7 +124,7 @@ func (s *state) handleSell(ctx context.Context, b *bot.Bot, update *models.Updat
 	}
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 2 {
-		return chathelper.Reply(ctx, b, update.Message, "Usage: /coin_sell <COIN> <usd_amount>\nSell enough coin to receive USD.\nAlternative: /coin_sell <usd_amount> <COIN>\nExample: /coin_sell BTC 10")
+		return chathelper.Reply(ctx, b, update.Message, "Usage: /coin_sell <coin> <usd_to_receive>\nSell enough coin to receive USD.\nAlternative: /coin_sell <usd_to_receive> <coin>\nExample: /coin_sell BTC 10")
 	}
 	parsed, err := parseCoinValueArgs(args, isSafeUSD, errInvalidUSDAmount)
 	if errors.Is(err, errInvalidUSDAmount) {
@@ -174,7 +174,7 @@ func (s *state) handleSell(ctx context.Context, b *bot.Bot, update *models.Updat
 func formatInsufficientSellMessage(coin CoinSymbol, requestedUSD, heldQty, priceUSD float64) string {
 	heldQty = normalizeAmount(heldQty)
 	if heldQty == 0 {
-		return "No " + coin.Symbol + " available to sell.\nTry /coin_buy " + coin.Symbol + " <usd_amount> first."
+		return "No " + coin.Symbol + " available to sell.\nTry /coin_buy " + coin.Symbol + " <usd_to_spend> first."
 	}
 	availableUSD := heldQty * priceUSD
 	return "Not enough " + coin.Symbol + " to sell " + FormatUSD(requestedUSD) + ".\n" +

internal/modules/coin/handlers_test.go

@@ -182,7 +182,7 @@ func TestHandleSellInsufficientCoin(t *testing.T) {
 		t.Fatalf("handleSell: %v", err)
 	}
 	text := rb.LastSent().Text()
-	for _, want := range []string{"No ETH available to sell.", "Try /coin_buy ETH <usd_amount> first."} {
+	for _, want := range []string{"No ETH available to sell.", "Try /coin_buy ETH <usd_to_spend> first."} {
 		if !strings.Contains(text, want) {
 			t.Fatalf("zero-holdings sell message missing %q in %q", want, text)
 		}

internal/modules/command_presentation.go

@@ -0,0 +1,59 @@
+package modules
+
+import "strings"
+
+// Invocation returns the copy-neutral command syntax shown in /help.
+func (c Command) Invocation() string {
+	invocation := "/" + c.Name
+	if parameters := strings.TrimSpace(c.Parameters); parameters != "" {
+		invocation += " " + parameters
+	}
+	return invocation
+}
+
+// InvocationSentence returns the command syntax with exactly one logical
+// sentence terminator. Variadic syntax ending in "..." is already terminated.
+func (c Command) InvocationSentence() string {
+	return withTerminalPunctuation(c.Invocation())
+}
+
+// ExampleInvocation returns the copyable example, defaulting to the command
+// itself for commands that take no parameters.
+func (c Command) ExampleInvocation() string {
+	if example := strings.TrimSpace(c.Example); example != "" {
+		return example
+	}
+	return "/" + c.Name
+}
+
+// SummarySentence normalizes a command summary to a sentence without
+// duplicating terminal punctuation supplied by the registration.
+func (c Command) SummarySentence() string {
+	return withTerminalPunctuation(c.Description)
+}
+
+// TelegramMenuDescription returns the single-line plain-text description used
+// by setMyCommands. Telegram renders the /command separately and does not
+// support code blocks in this surface.
+func (c Command) TelegramMenuDescription() string {
+	var sb strings.Builder
+	if parameters := strings.TrimSpace(c.Parameters); parameters != "" {
+		sb.WriteString(withTerminalPunctuation(parameters))
+		sb.WriteByte(' ')
+	}
+	sb.WriteString(c.SummarySentence())
+	sb.WriteString(" Example: ")
+	sb.WriteString(c.ExampleInvocation())
+	return sb.String()
+}
+
+func withTerminalPunctuation(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return ""
+	}
+	if strings.HasSuffix(value, ".") || strings.HasSuffix(value, "!") || strings.HasSuffix(value, "?") {
+		return value
+	}
+	return value + "."
+}

internal/modules/command_presentation_test.go

@@ -0,0 +1,59 @@
+package modules
+
+import "testing"
+
+func TestCommandPresentation(t *testing.T) {
+	tests := []struct {
+		name       string
+		command    Command
+		invocation string
+		example    string
+		menu       string
+	}{
+		{
+			name: "parameters and explicit example",
+			command: Command{
+				Name:        "stock_buy",
+				Parameters:  "<quantity> <ticker>",
+				Description: "Buy VN stock at market price",
+				Example:     "/stock_buy 100 TCB",
+			},
+			invocation: "/stock_buy <quantity> <ticker>",
+			example:    "/stock_buy 100 TCB",
+			menu:       "<quantity> <ticker>. Buy VN stock at market price. Example: /stock_buy 100 TCB",
+		},
+		{
+			name:       "no parameters uses command as example",
+			command:    Command{Name: "ping", Description: "Health check!"},
+			invocation: "/ping",
+			example:    "/ping",
+			menu:       "Health check! Example: /ping",
+		},
+		{
+			name: "variadic parameters keep ellipsis",
+			command: Command{
+				Name:        "random",
+				Parameters:  "<options(comma-separated)>",
+				Description: "Pick one option",
+				Example:     "/random pizza, sushi",
+			},
+			invocation: "/random <options(comma-separated)>",
+			example:    "/random pizza, sushi",
+			menu:       "<options(comma-separated)>. Pick one option. Example: /random pizza, sushi",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := tc.command.Invocation(); got != tc.invocation {
+				t.Errorf("Invocation() = %q, want %q", got, tc.invocation)
+			}
+			if got := tc.command.ExampleInvocation(); got != tc.example {
+				t.Errorf("ExampleInvocation() = %q, want %q", got, tc.example)
+			}
+			if got := tc.command.TelegramMenuDescription(); got != tc.menu {
+				t.Errorf("TelegramMenuDescription() = %q, want %q", got, tc.menu)
+			}
+		})
+	}
+}

internal/modules/gold/gold.go

@@ -20,18 +20,24 @@ func New(deps modules.Deps) modules.Module {
 				Name:        "gold_topup",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Top up VND to your gold account",
+				Parameters:  "<vnd_amount>",
+				Example:     "/gold_topup 5000000",
 				Handler:     s.handleTopup,
 			},
 			{
 				Name:        "gold_buy",
 				Visibility:  modules.VisibilityPublic,
-				Description: "Buy gold at SJC sell price (luong)",
+				Description: "Buy gold at SJC sell price",
+				Parameters:  "<luong>",
+				Example:     "/gold_buy 1",
 				Handler:     s.handleBuy,
 			},
 			{
 				Name:        "gold_sell",
 				Visibility:  modules.VisibilityPublic,
-				Description: "Sell gold at SJC buy price (luong)",
+				Description: "Sell gold at SJC buy price",
+				Parameters:  "<luong>",
+				Example:     "/gold_sell 0.5",
 				Handler:     s.handleSell,
 			},
 			{

internal/modules/gold/handlers.go

@@ -52,7 +52,7 @@ func (s *state) handleTopup(ctx context.Context, b *bot.Bot, update *models.Upda
 	}
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 1 {
-		return chathelper.Reply(ctx, b, update.Message, "Usage: /gold_topup <amount>\nExample: /gold_topup 5000000")
+		return chathelper.Reply(ctx, b, update.Message, "Usage: /gold_topup <vnd_amount>\nExample: /gold_topup 5000000")
 	}
 	amount, ok := parsePositiveFinite(args[0])
 	if !ok || !isSafeVND(amount) {

internal/modules/gold/handlers_validation_test.go

@@ -17,7 +17,7 @@ func TestHandlersRejectExtraArgs(t *testing.T) {
 		text string
 		want string
 	}{
-		{name: "topup currency", text: "/gold_topup 100 USD", want: "Usage: /gold_topup <amount>"},
+		{name: "topup currency", text: "/gold_topup 100 USD", want: "Usage: /gold_topup <vnd_amount>"},
 		{name: "buy unit", text: "/gold_buy 1 oz", want: "Usage: /gold_buy <luong>"},
 		{name: "sell symbol", text: "/gold_sell 1 SJC", want: "Usage: /gold_sell <luong>"},
 	}

internal/modules/lol/lol.go

@@ -26,6 +26,8 @@ func New(deps modules.Deps) modules.Module {
 				Name:        "lol",
 				Visibility:  modules.VisibilityPublic,
 				Description: "LoL matches for a date (dd, dd-mm, dd/mm, ddmm, or full date; default today)",
+				Parameters:  "[date]",
+				Example:     "/lol 21-07-2026",
 				Handler:     s.handleSchedule,
 			},
 			{

internal/modules/loldle/loldle.go

@@ -20,6 +20,8 @@ func New(deps modules.Deps) modules.Module {
 				Name:        "loldle",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Classic loldle — guess the current champion",
+				Parameters:  "[champion]",
+				Example:     "/loldle Ahri",
 				Handler:     s.handleLoldle,
 			},
 			{

internal/modules/misc/handlers_test.go

@@ -142,8 +142,8 @@ func TestWheelOfNames_UsageWhenMissingOptions(t *testing.T) {
 			rb, _ := installMisc(t, 999)
 			rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(7, text))
 
-			if got := rb.LastSent().Text(); got != wheelOfNamesUsage {
-				t.Errorf("wheelofnames reply = %q, want usage %q", got, wheelOfNamesUsage)
+			if got := rb.LastSent().Text(); got != wheelUsage {
+				t.Errorf("wheelofnames reply = %q, want usage %q", got, wheelUsage)
 			}
 		})
 	}

internal/modules/misc/misc.go

@@ -128,10 +128,18 @@ func senderMention(u *models.User) string {
 }
 
 func disclaimerCommand(name, description, defaultTarget string, allowCustomTarget bool) modules.Command {
+	parameters := ""
+	example := ""
+	if allowCustomTarget {
+		parameters = "[target...]"
+		example = "/" + name + " FBI"
+	}
 	return modules.Command{
 		Name:        name,
 		Visibility:  modules.VisibilityPublic,
 		Description: description,
+		Parameters:  parameters,
+		Example:     example,
 		Handler: func(ctx context.Context, b *bot.Bot, update *models.Update) error {
 			if update.Message == nil {
 				return nil

internal/modules/misc/random_picker.go

@@ -12,7 +12,7 @@ import (
 	"github.com/tiennm99/miti99bot/internal/modules/util/chathelper"
 )
 
-const randomUsage = "Usage: /random <option1>, <option2>, ..."
+const randomUsage = "Usage: /random <options(comma-separated)>"
 
 func splitWheelOptions(arg string) []string {
 	parts := strings.Split(arg, ",")
@@ -30,6 +30,8 @@ func randomCommand() modules.Command {
 		Name:        "random",
 		Visibility:  modules.VisibilityPublic,
 		Description: "Pick one random comma-separated option",
+		Parameters:  "<options(comma-separated)>",
+		Example:     "/random pizza, sushi, pho",
 		Handler: func(ctx context.Context, b *bot.Bot, update *models.Update) error {
 			if update.Message == nil {
 				return nil

internal/modules/misc/wheelofnames_command.go

@@ -15,7 +15,6 @@ import (
 )
 
 const (
-	wheelOfNamesUsage          = "Usage: /wheelofnames <option1>, <option2>, ..."
 	wheelFilename              = "wheelofnames.gif"
 	wheelResultCaptionMaxRunes = 900
 )
@@ -25,13 +24,15 @@ func wheelOfNamesCommand() modules.Command {
 		Name:        "wheelofnames",
 		Visibility:  modules.VisibilityPublic,
 		Description: "Pick one comma-separated option with wheel GIF when configured",
+		Parameters:  "<options(comma-separated)>",
+		Example:     "/wheelofnames pizza, sushi, pho",
 		Handler: func(ctx context.Context, b *bot.Bot, update *models.Update) error {
 			if update.Message == nil {
 				return nil
 			}
 			options := splitWheelOptions(chathelper.ArgAfterCommand(update.Message.Text))
 			if len(options) == 0 {
-				return chathelper.Reply(ctx, b, update.Message, wheelOfNamesUsage)
+				return chathelper.Reply(ctx, b, update.Message, wheelUsage)
 			}
 			winner := pickWheelOption(options)
 			animation, err := renderWheelOfNamesAnimation(ctx, options, winner)
@@ -63,6 +64,8 @@ func wheelOfNamesCommand() modules.Command {
 	}
 }
 
+const wheelUsage = "Usage: /wheelofnames <options(comma-separated)>"
+
 func wheelResultCaption(result string) string {
 	result = truncateWheelResultCaption(result)
 	return `Result: <span class="tg-spoiler">` + html.EscapeString(result) + `</span>`

internal/modules/module.go

@@ -38,7 +38,9 @@ type CronHandler func(ctx context.Context, deps Deps) error
 type Command struct {
 	Name        string         // ^[a-z0-9_]{1,32}$ — Telegram BotFather rules
 	Visibility  Visibility     // public/protected/private
-	Description string         // shown in /help (required, non-empty)
+	Description string         // concise summary shown in command discovery (required, non-empty)
+	Parameters  string         // optional syntax after the command, e.g. "<quantity> <ticker>"
+	Example     string         // optional full invocation; defaults to "/" + Name
 	Handler     CommandHandler // required
 }
 

internal/modules/stats/views.go

@@ -20,7 +20,7 @@ const statsUsage = `Usage:
 /stats
 /stats users
 /stats user <username>
-/stats cmd <name>`
+/stats cmd <command_name>`
 
 type row struct {
 	display string
@@ -32,6 +32,8 @@ func statsCommand(c *counter) modules.Command {
 		Name:        "stats",
 		Visibility:  modules.VisibilityPublic,
 		Description: "Show command usage statistics",
+		Parameters:  "[users | user <username> | cmd <command_name>]",
+		Example:     "/stats user alice",
 		Handler: func(ctx context.Context, b *bot.Bot, update *models.Update) error {
 			if update.Message == nil {
 				return nil

internal/modules/stock/handlers.go

@@ -79,7 +79,7 @@ func parsePositiveFinite(raw string) (float64, bool) {
 func (s *state) handlePrice(ctx context.Context, b *bot.Bot, update *models.Update) error {
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 1 {
-		return chathelper.Reply(ctx, b, update.Message, "Usage: /stock_price <TICKER>\nExample: /stock_price TCB")
+		return chathelper.Reply(ctx, b, update.Message, "Usage: /stock_price <ticker>\nExample: /stock_price TCB")
 	}
 	symbol, err := normalizeStockSymbol(args[0])
 	if err != nil {
@@ -109,7 +109,7 @@ func (s *state) handleTopup(ctx context.Context, b *bot.Bot, update *models.Upda
 	}
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 1 {
-		return chathelper.Reply(ctx, b, update.Message, "Usage: /stock_topup <amount>\nExample: /stock_topup 5000000")
+		return chathelper.Reply(ctx, b, update.Message, "Usage: /stock_topup <vnd_amount>\nExample: /stock_topup 5000000")
 	}
 	amount, ok := parsePositiveFinite(args[0])
 	if !ok {
@@ -141,7 +141,7 @@ func (s *state) handleBuy(ctx context.Context, b *bot.Bot, update *models.Update
 	}
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 2 {
-		return chathelper.Reply(ctx, b, update.Message, "Usage: /stock_buy <qty> <TICKER>\nExample: /stock_buy 100 TCB")
+		return chathelper.Reply(ctx, b, update.Message, "Usage: /stock_buy <quantity> <ticker>\nExample: /stock_buy 100 TCB")
 	}
 	qty, err := strconv.ParseInt(args[0], 10, 64)
 	if err != nil || qty <= 0 {
@@ -198,7 +198,7 @@ func (s *state) handleSell(ctx context.Context, b *bot.Bot, update *models.Updat
 	}
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 2 {
-		return chathelper.Reply(ctx, b, update.Message, "Usage: /stock_sell <qty> <TICKER>\nExample: /stock_sell 100 TCB")
+		return chathelper.Reply(ctx, b, update.Message, "Usage: /stock_sell <quantity> <ticker>\nExample: /stock_sell 100 TCB")
 	}
 	qty, err := strconv.ParseInt(args[0], 10, 64)
 	if err != nil || qty <= 0 {
@@ -258,7 +258,7 @@ func (s *state) handleCashDividend(ctx context.Context, b *bot.Bot, update *mode
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 2 {
 		return chathelper.Reply(ctx, b, update.Message,
-			"Usage: /stock_cash_dividend <vnd_per_share> <TICKER>\nExample: /stock_cash_dividend 1500 TCB")
+			"Usage: /stock_cash_dividend <vnd_per_share> <ticker>\nExample: /stock_cash_dividend 1500 TCB")
 	}
 	vndPerShare, ok := parsePositiveWhole(args[0])
 	if !ok {
@@ -314,7 +314,7 @@ func (s *state) handleShareDividend(ctx context.Context, b *bot.Bot, update *mod
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 2 {
 		return chathelper.Reply(ctx, b, update.Message,
-			"Usage: /stock_share_dividend <owned:new> <TICKER>\nExample: /stock_share_dividend 100:10 TCB")
+			"Usage: /stock_share_dividend <ratio(owned:new)> <ticker>\nExample: /stock_share_dividend 100:10 TCB")
 	}
 	ratio, ok := parseShareRatio(args[0])
 	if !ok {
@@ -374,7 +374,7 @@ func (s *state) handleDividend(ctx context.Context, b *bot.Bot, update *models.U
 	args := argsAfterCommand(update.Message.Text)
 	if len(args) != 3 {
 		return chathelper.Reply(ctx, b, update.Message,
-			"Usage: /stock_dividend <vnd_per_share> <owned:new> <TICKER>\nExample: /stock_dividend 1500 100:10 TCB")
+			"Usage: /stock_dividend <vnd_per_share> <ratio(owned:new)> <ticker>\nExample: /stock_dividend 1500 100:10 TCB")
 	}
 	vndPerShare, ok := parsePositiveWhole(args[0])
 	if !ok {

internal/modules/stock/handlers_test.go

@@ -72,7 +72,7 @@ func TestHandlePriceUsage(t *testing.T) {
 	if err := s.handlePrice(context.Background(), rb.Bot, testutil.NewPrivateMessage(7, "/stock_price")); err != nil {
 		t.Fatalf("handlePrice: %v", err)
 	}
-	rb.AssertSentText(t, "Usage: /stock_price <TICKER>")
+	rb.AssertSentText(t, "Usage: /stock_price <ticker>")
 }
 
 func TestMutableHandlersRejectExtraArgs(t *testing.T) {
@@ -94,7 +94,7 @@ func TestMutableHandlersRejectExtraArgs(t *testing.T) {
 			run: func(ctx context.Context, rb *testutil.RecordingBot, upd *models.Update) error {
 				return s.handleTopup(ctx, rb.Bot, upd)
 			},
-			want: "Usage: /stock_topup <amount>",
+			want: "Usage: /stock_topup <vnd_amount>",
 		},
 		{
 			name: "buy",
@@ -102,7 +102,7 @@ func TestMutableHandlersRejectExtraArgs(t *testing.T) {
 			run: func(ctx context.Context, rb *testutil.RecordingBot, upd *models.Update) error {
 				return s.handleBuy(ctx, rb.Bot, upd)
 			},
-			want: "Usage: /stock_buy <qty> <TICKER>",
+			want: "Usage: /stock_buy <quantity> <ticker>",
 		},
 		{
 			name: "sell",
@@ -110,7 +110,7 @@ func TestMutableHandlersRejectExtraArgs(t *testing.T) {
 			run: func(ctx context.Context, rb *testutil.RecordingBot, upd *models.Update) error {
 				return s.handleSell(ctx, rb.Bot, upd)
 			},
-			want: "Usage: /stock_sell <qty> <TICKER>",
+			want: "Usage: /stock_sell <quantity> <ticker>",
 		},
 		{
 			name: "cash dividend",
@@ -118,7 +118,7 @@ func TestMutableHandlersRejectExtraArgs(t *testing.T) {
 			run: func(ctx context.Context, rb *testutil.RecordingBot, upd *models.Update) error {
 				return s.handleCashDividend(ctx, rb.Bot, upd)
 			},
-			want: "Usage: /stock_cash_dividend <vnd_per_share> <TICKER>",
+			want: "Usage: /stock_cash_dividend <vnd_per_share> <ticker>",
 		},
 		{
 			name: "share dividend",
@@ -126,7 +126,7 @@ func TestMutableHandlersRejectExtraArgs(t *testing.T) {
 			run: func(ctx context.Context, rb *testutil.RecordingBot, upd *models.Update) error {
 				return s.handleShareDividend(ctx, rb.Bot, upd)
 			},
-			want: "Usage: /stock_share_dividend <owned:new> <TICKER>",
+			want: "Usage: /stock_share_dividend <ratio(owned:new)> <ticker>",
 		},
 		{
 			name: "dividend",
@@ -134,7 +134,7 @@ func TestMutableHandlersRejectExtraArgs(t *testing.T) {
 			run: func(ctx context.Context, rb *testutil.RecordingBot, upd *models.Update) error {
 				return s.handleDividend(ctx, rb.Bot, upd)
 			},
-			want: "Usage: /stock_dividend <vnd_per_share> <owned:new> <TICKER>",
+			want: "Usage: /stock_dividend <vnd_per_share> <ratio(owned:new)> <ticker>",
 		},
 	}
 	for _, tc := range cases {

internal/modules/stock/stock.go

@@ -14,42 +14,56 @@ func New(deps modules.Deps) modules.Module {
 				Name:        "stock_price",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Show current VN stock price",
+				Parameters:  "<ticker>",
+				Example:     "/stock_price TCB",
 				Handler:     s.handlePrice,
 			},
 			{
 				Name:        "stock_topup",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Top up VND to your stock account",
+				Parameters:  "<vnd_amount>",
+				Example:     "/stock_topup 5000000",
 				Handler:     s.handleTopup,
 			},
 			{
 				Name:        "stock_buy",
 				Visibility:  modules.VisibilityPublic,
-				Description: "Buy VN stock at market price (qty TICKER)",
+				Description: "Buy VN stock at market price",
+				Parameters:  "<quantity> <ticker>",
+				Example:     "/stock_buy 100 TCB",
 				Handler:     s.handleBuy,
 			},
 			{
 				Name:        "stock_sell",
 				Visibility:  modules.VisibilityPublic,
-				Description: "Sell VN stock back to VND (qty TICKER)",
+				Description: "Sell VN stock back to VND",
+				Parameters:  "<quantity> <ticker>",
+				Example:     "/stock_sell 100 TCB",
 				Handler:     s.handleSell,
 			},
 			{
 				Name:        "stock_cash_dividend",
 				Visibility:  modules.VisibilityPublic,
-				Description: "Record cash dividend (VND/share TICKER)",
+				Description: "Record cash dividend",
+				Parameters:  "<vnd_per_share> <ticker>",
+				Example:     "/stock_cash_dividend 1500 TCB",
 				Handler:     s.handleCashDividend,
 			},
 			{
 				Name:        "stock_share_dividend",
 				Visibility:  modules.VisibilityPublic,
-				Description: "Record share dividend (owned:new TICKER)",
+				Description: "Record share dividend",
+				Parameters:  "<ratio(owned:new)> <ticker>",
+				Example:     "/stock_share_dividend 100:10 TCB",
 				Handler:     s.handleShareDividend,
 			},
 			{
 				Name:        "stock_dividend",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Record cash and share dividend",
+				Parameters:  "<vnd_per_share> <ratio(owned:new)> <ticker>",
+				Example:     "/stock_dividend 1500 100:10 TCB",
 				Handler:     s.handleDividend,
 			},
 			{

internal/modules/util/handlers_test.go

@@ -87,6 +87,12 @@ func TestHelp_RendersHTML(t *testing.T) {
 	if !strings.Contains(got.Text(), "<b>util</b>") {
 		t.Errorf("/help body missing util section; got %q", got.Text())
 	}
+	if !strings.Contains(got.Text(), "/help. Show all available commands.") {
+		t.Errorf("/help body missing formatted command summary; got %q", got.Text())
+	}
+	if !strings.Contains(got.Text(), "<pre>/help</pre>") {
+		t.Errorf("/help body missing copyable example; got %q", got.Text())
+	}
 }
 
 func TestStickerID_NoReply_ShowsUsage(t *testing.T) {

internal/modules/util/help.go

@@ -32,16 +32,10 @@ func RenderHelp(reg *modules.Registry) string {
 		return "no commands registered\n\n" + supportFooter
 	}
 
-	type entry struct {
-		name        string
-		description string
-	}
-	byModule := make(map[string][]entry, len(reg.Modules))
+	byModule := make(map[string][]modules.Command, len(reg.Modules))
 
 	for _, c := range reg.PublicCommands() {
-		byModule[ownerOf(reg, c.Name)] = append(byModule[ownerOf(reg, c.Name)], entry{
-			name: c.Name, description: c.Description,
-		})
+		byModule[ownerOf(reg, c.Name)] = append(byModule[ownerOf(reg, c.Name)], c)
 	}
 
 	var sections []string
@@ -52,8 +46,11 @@ func RenderHelp(reg *modules.Registry) string {
 		}
 		var sb strings.Builder
 		fmt.Fprintf(&sb, "<b>%s</b>", html.EscapeString(mod.Name))
-		for _, e := range es {
-			fmt.Fprintf(&sb, "\n/%s — %s", e.name, html.EscapeString(e.description))
+		for _, command := range es {
+			fmt.Fprintf(&sb, "\n%s %s\n<pre>%s</pre>",
+				html.EscapeString(command.InvocationSentence()),
+				html.EscapeString(command.SummarySentence()),
+				html.EscapeString(command.ExampleInvocation()))
 		}
 		sections = append(sections, sb.String())
 	}

internal/modules/util/help_test.go

@@ -51,7 +51,8 @@ func TestRenderHelp_GroupsByModuleAndSkipsNonPublic(t *testing.T) {
 	for _, want := range []string{
 		"<b>alpha</b>",
 		"<b>beta</b>",
-		"/a_pub — alpha public",
+		"/a_pub. alpha public.",
+		"<pre>/a_pub</pre>",
 		// HTML in user descriptions must be escaped.
 		"beta &lt;i&gt;desc&lt;/i&gt;",
 		// Locks html.EscapeString contract: & → &amp;, " → &#34;.
@@ -71,6 +72,34 @@ func TestRenderHelp_GroupsByModuleAndSkipsNonPublic(t *testing.T) {
 	}
 }
 
+func TestRenderHelp_ShowsParametersAndCopyableExample(t *testing.T) {
+	command := modules.Command{
+		Name:        "buy",
+		Visibility:  modules.VisibilityPublic,
+		Description: "Buy & hold",
+		Parameters:  "<quantity> <ticker>",
+		Example:     "/buy 100 TCB",
+		Handler:     helpTestNoop,
+	}
+	reg, err := modules.Build(
+		[]string{"stock"},
+		map[string]modules.Factory{"stock": fakeFactory("stock", []modules.Command{command})},
+		storage.NewMemoryProvider(),
+		modules.BuildOptions{},
+	)
+	if err != nil {
+		t.Fatalf("Build: %v", err)
+	}
+
+	out := util.RenderHelp(reg)
+	if !strings.Contains(out, "/buy &lt;quantity&gt; &lt;ticker&gt;. Buy &amp; hold.") {
+		t.Fatalf("help missing formatted invocation and summary:\n%s", out)
+	}
+	if !strings.Contains(out, "<pre>/buy 100 TCB</pre>") {
+		t.Fatalf("help missing copyable example:\n%s", out)
+	}
+}
+
 func TestRenderHelp_ModuleOrderMatchesEnvOrder(t *testing.T) {
 	cmd := func(name string) modules.Command {
 		return modules.Command{Name: name, Visibility: modules.VisibilityPublic, Description: name, Handler: helpTestNoop}

internal/modules/validate.go

@@ -3,10 +3,14 @@ package modules
 import (
 	"fmt"
 	"regexp"
+	"strings"
+	"unicode/utf8"
 )
 
 var commandNameRe = regexp.MustCompile(`^[a-z0-9_]{1,32}$`)
 
+const telegramCommandDescriptionMaxRunes = 256
+
 func validateCommand(c Command) error {
 	if !commandNameRe.MatchString(c.Name) {
 		return fmt.Errorf("command name %q must match %s", c.Name, commandNameRe)
@@ -16,9 +20,27 @@ func validateCommand(c Command) error {
 	default:
 		return fmt.Errorf("command %q: unknown visibility %d", c.Name, c.Visibility)
 	}
-	if c.Description == "" {
+	if strings.TrimSpace(c.Description) == "" {
 		return fmt.Errorf("command %q: description is required", c.Name)
 	}
+	if strings.ContainsAny(c.Description, "\r\n") {
+		return fmt.Errorf("command %q: description must be single-line", c.Name)
+	}
+	if strings.ContainsAny(c.Parameters, "\r\n") {
+		return fmt.Errorf("command %q: parameters must be single-line", c.Name)
+	}
+	if strings.ContainsAny(c.Example, "\r\n") {
+		return fmt.Errorf("command %q: example must be single-line", c.Name)
+	}
+	if example := strings.TrimSpace(c.Example); example != "" {
+		prefix := "/" + c.Name
+		if example != prefix && !strings.HasPrefix(example, prefix+" ") {
+			return fmt.Errorf("command %q: example must invoke %s", c.Name, prefix)
+		}
+	}
+	if c.Visibility == VisibilityPublic && utf8.RuneCountInString(c.TelegramMenuDescription()) > telegramCommandDescriptionMaxRunes {
+		return fmt.Errorf("command %q: Telegram menu description exceeds %d characters", c.Name, telegramCommandDescriptionMaxRunes)
+	}
 	if c.Handler == nil {
 		return fmt.Errorf("command %q: handler is nil", c.Name)
 	}

internal/modules/validate_test.go

@@ -2,6 +2,7 @@ package modules
 
 import (
 	"context"
+	"strings"
 	"testing"
 
 	"github.com/go-telegram/bot"
@@ -29,6 +30,46 @@ func TestValidateCommand_RejectsBadNames(t *testing.T) {
 	}
 }
 
+func TestValidateCommand_RejectsInvalidPresentationMetadata(t *testing.T) {
+	tests := []struct {
+		name    string
+		command Command
+	}{
+		{
+			name:    "blank description",
+			command: Command{Name: "ok", Visibility: VisibilityPublic, Description: "   ", Handler: okHandler},
+		},
+		{
+			name:    "multiline description",
+			command: Command{Name: "ok", Visibility: VisibilityPublic, Description: "one\ntwo", Handler: okHandler},
+		},
+		{
+			name:    "multiline parameters",
+			command: Command{Name: "ok", Visibility: VisibilityPublic, Description: "d", Parameters: "<a>\n<b>", Handler: okHandler},
+		},
+		{
+			name:    "multiline example",
+			command: Command{Name: "ok", Visibility: VisibilityPublic, Description: "d", Example: "/ok one\n/ok two", Handler: okHandler},
+		},
+		{
+			name:    "example invokes another command",
+			command: Command{Name: "ok", Visibility: VisibilityPublic, Description: "d", Example: "/other", Handler: okHandler},
+		},
+		{
+			name:    "native description too long",
+			command: Command{Name: "ok", Visibility: VisibilityPublic, Description: strings.Repeat("x", 250), Handler: okHandler},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if err := validateCommand(tc.command); err == nil {
+				t.Fatal("expected validation error")
+			}
+		})
+	}
+}
+
 func TestValidateCommand_AcceptsLegalNames(t *testing.T) {
 	for _, name := range []string{"ping", "do_it", "a", "abc123", "x_1_y"} {
 		if err := validateCommand(Command{Name: name, Visibility: VisibilityPublic, Description: "d", Handler: okHandler}); err != nil {

internal/modules/wordle/wordle.go

@@ -22,6 +22,8 @@ func New(deps modules.Deps) modules.Module {
 				Name:        "wordle",
 				Visibility:  modules.VisibilityPublic,
 				Description: "Classic wordle — guess the 5-letter word",
+				Parameters:  "[word]",
+				Example:     "/wordle apple",
 				Handler:     s.handleWordle,
 			},
 			{