# Telegram Link Confirmation Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make Telegram linking confirmable from both the platform and the bot so users can see success, expiry, and missing-token guidance immediately.

**Architecture:** Keep `/account/telegram/link` as the entrypoint, but redirect it to a token-owned wait page with polling. Handle `/start` and `/start {token}` explicitly in the webhook and send direct bot replies for success/failure instead of relying only on queued notifications.

**Tech Stack:** Laravel 12, Blade, existing Telegram module, short-lived link tokens, webhook controller, HTTP polling.

---

### Task 1: Add wait-page flow for link tokens

**Files:**
- Modify: `C:/Users/a-djoudi/apps/ecoinv3/routes/web.php`
- Modify: `C:/Users/a-djoudi/apps/ecoinv3/app/Http/Controllers/Telegram/TelegramLinkController.php`
- Create: `C:/Users/a-djoudi/apps/ecoinv3/resources/views/auth/telegram-link-wait.blade.php`

- [ ] Write a failing feature test for redirecting `/account/telegram/link` into a wait page.
- [ ] Add wait/status routes and token ownership checks.
- [ ] Render a wait page that opens the bot and polls link status.

### Task 2: Make `/start` explicit and user-facing

**Files:**
- Modify: `C:/Users/a-djoudi/apps/ecoinv3/app/Http/Controllers/Webhooks/TelegramWebhookController.php`
- Modify: `C:/Users/a-djoudi/apps/ecoinv3/lang/ar/telegram.php`
- Modify: `C:/Users/a-djoudi/apps/ecoinv3/lang/fr/telegram.php`

- [ ] Write failing tests for `/start` without token and `/start {token}` success confirmation.
- [ ] Send direct localized bot replies for success, expiry, invalid token, already used, and already linked cases.
- [ ] Keep existing interaction tracking intact.

### Task 3: Verify end-to-end behavior and docs

**Files:**
- Modify: `C:/Users/a-djoudi/apps/ecoinv3/tests/Feature/Telegram/TelegramPlatformTest.php`
- Modify: `C:/Users/a-djoudi/apps/ecoinv3/docs/telegram_platform_architecture.md`

- [ ] Cover wait-page status polling behavior.
- [ ] Update architecture docs with the new confirmation flow.
- [ ] Run targeted verification commands and record any environment-only blockers.