ADR-0001 — No slash commands, buttons only

Status. Accepted. Date. 2026-05-18.

Context

Telegram bots typically expose a set of /-commands listed in BotFather. Power users learn them; new users do not. Commands are also untranslated, untyped, hard to tier-gate, and they leak the bot's capability surface.

Decision

The bot accepts exactly one /-command: /start. Telegram requires it for first contact and deep links. Every other interaction is a button, an FSM dialog or the Mini App.

Owner and admin capabilities are not exposed via secret commands. They appear as additional buttons in the main menu, gated by RoleFilter.

Consequences

• Discoverability is much higher — every capability is visible.
• Localization is consistent — every label is an i18n key.
• Tier gating is trivial — invisible buttons cannot be invoked.
• CI enforces this via scripts/no_new_commands.sh and a ruff rule.
• The Mini App is the primary surface for anything richer than a tap.

Alternatives considered

• Keep commands. Rejected: prior projects suffered from undiscoverable features hidden behind commands users never typed.
• Hybrid (commands as shortcuts to buttons). Rejected: doubles the surface area for tests and i18n; one more thing to keep in sync.