feat(commands): improve discovery and normalize parameters

docs/deploy-coolify-selfhosted.md

@@ -136,7 +136,11 @@ Successful GIF replies include the result behind Telegram spoiler formatting.
 
 The bot registers its Telegram command menu from loaded public modules on
 every startup. The Go module registry is the single source of truth; no separate
-command-menu file or manual registration step is required.
+command-menu file or manual registration step is required. A command's
+description plus optional `Parameters` and `Example` metadata feed both
+surfaces. Telegram renders the command name separately and accepts only a
+single-line plain-text description, while `/help` can put the example in a
+copyable code block. An omitted example defaults to the bare command.
 
 ## Operations
 

docs/journals/260721-1011-telegram-command-discovery.md

@@ -0,0 +1,60 @@
+# Telegram Command Discovery Journal
+
+## Context
+
+Telegram's native command menu and `/help` exposed only short descriptions,
+leaving users to discover parameters and examples through failed invocations or
+source documentation.
+
+## What Changed
+
+- Extended the shared command registration with `Parameters` and `Example`
+  metadata and presentation helpers used by both discovery surfaces.
+- Added metadata for all 40 public commands, including the exact stats grammar:
+  `[users | user <username> | cmd <command_name>]`.
+- Normalized placeholders to lowercase descriptive names, including meaningful
+  units or currencies; `[...]` marks optional input, `...` remaining free text,
+  and parentheses structured input.
+- Normalized `/wheelofnames` to `<options(comma-separated)>` across metadata,
+  usage text, and tests; its example remains
+  `/wheelofnames pizza, sushi, pho`.
+- Finalized dividend placeholders as `<vnd_per_share> <ticker>`,
+  `<ratio(owned:new)> <ticker>`, and
+  `<vnd_per_share> <ratio(owned:new)> <ticker>` for cash, share, and combined
+  commands. Examples and parsing remain unchanged.
+- Native menu descriptions now combine parameters, summary, and example on one
+  plain-text line. Registration validation rejects multiline metadata, examples
+  for another command, and public descriptions over Telegram's 256-character
+  limit.
+- `/help` now renders each invocation and summary together, followed by a
+  copyable HTML `<pre>` example. Dynamic command fields are HTML-escaped.
+- Updated user and deployment documentation for the shared registry behavior.
+
+## Reflection
+
+Keeping syntax and examples beside each handler registration prevents the
+native menu, `/help`, and implementation from drifting independently. The
+native surface stays compact, while `/help` uses the richer layout Telegram
+supports without sacrificing safe HTML rendering.
+
+## Decisions
+
+- Existing command names, handlers, parsers, and persisted data remain
+  unchanged; normalization is presentation-only.
+- No command was added, renamed, or deleted, so no stats migration is needed.
+- Commands without parameters default their example to the command invocation.
+- The complete `/help` output remains within Telegram's 4,096-character limit.
+
+## Verification
+
+- Passed: command presentation, validation, menu, and `/help` tests for all 40
+  public commands.
+- Passed: `go test ./...`, including real MongoDB Testcontainers suites.
+- Passed: `go vet ./...`
+- Passed: `go build ./...`
+- Passed: `golangci-lint run`
+
+## Next Steps
+
+- Require parameter and example metadata updates alongside future public
+  command contract changes.