# Telegram Link Confirmation Design

## Goal

Close the Telegram linking flow end-to-end so users do not leave the platform guessing whether linking succeeded after pressing `Start` in the bot.

## Problems Observed

- `/account/telegram/link` opened the bot directly, but the platform had no confirmation state after the user left for Telegram.
- The bot only handled `/start {token}`. If Telegram delivered `/start` without a token, the user got no guidance.
- Success confirmation depended on queued notification delivery, so a missing queue worker could make a successful link look broken.

## Design

### 1. Platform wait page

- Keep `GET /account/telegram/link` as the entrypoint.
- Generate a short-lived `telegram_link_tokens` row, then redirect to a wait page owned by that token.
- The wait page:
  - opens the bot in a new tab/window,
  - polls a status endpoint for the token,
  - shows `pending`, `linked`, or `expired` states,
  - gives the user a manual `Open Telegram Bot` fallback button.

### 2. Bot-side confirmation

- Treat every `/start...` message explicitly.
- If `/start` arrives without a token:
  - reply with a clear instruction to return to the platform and click the link button again.
- If `/start {token}` succeeds:
  - complete the link immediately,
  - send a direct success message from the webhook handler instead of relying only on queue delivery.
- If `/start {token}` fails:
  - send a direct localized failure reason when possible.

### 3. Safety boundaries

- Token wait/status pages require authentication and token ownership.
- Tokens remain single-use and short-lived.
- No direct business mutations beyond linking state already owned by the Telegram module.

## Success Criteria

- Clicking `Link Telegram` leads to a visible in-platform progress screen.
- Pressing `Start` in Telegram changes the platform page to success without manual refresh.
- `/start` without token no longer fails silently.
- Missing queue workers no longer hide successful linking from the user.