docs: Add Common Pitfall #54 - Telegram webhook vs polling conflict

.github/copilot-instructions.md

@@ -5518,6 +5518,55 @@ trade.realizedPnL += actualRealizedPnL  // NOT: result.realizedPnL from SDK
       * Without this fix, external closures lose ALL revenge opportunities
       * This completes revenge system coverage for all exit scenarios
 
+54. **Telegram webhook conflicts with polling bot (CRITICAL - Fixed Dec 4, 2025):**
+    - **Symptom:** Python Telegram bot crashes with "Conflict: can't use getUpdates method while webhook is active"
+    - **User report:** `/status` command returns weird n8n test message: "✅ Bot works! You said: {{ $json.message.text }}"
+    - **Root Cause:** n8n had active Telegram webhook that intercepted ALL messages before Python bot could receive them
+    - **Why it broke:**
+      * Telegram API only allows ONE update method: either webhooks OR polling, not both
+      * n8n workflow set webhook at `https://flow.egonetix.de/webhook/93b61e0a-f509-4994-9f28-b16468c90ac7/webhook`
+      * Python bot using polling (`getUpdates`) crashed immediately
+      * n8n webhook sent test messages with broken template syntax (missing `=` in `{{ }}`)
+    - **Real incident (Dec 4, 2025):**
+      * User sent `/status` → received "✅ Bot works! You said: {{ $json.message.text }}"
+      * Python bot logs showed continuous crashes: `telegram.error.Conflict: can't use getUpdates`
+      * Bot running but couldn't process ANY commands
+      * Container healthy but functionality broken
+    - **Detection:**
+    ```bash
+    # Check webhook status
+    curl -s "https://api.telegram.org/bot{TOKEN}/getWebhookInfo" | python3 -m json.tool
+    # Shows: "url": "https://flow.egonetix.de/webhook/..." (webhook active)
+    
+    # Check bot logs
+    docker logs telegram-trade-bot
+    # Shows: telegram.error.Conflict (webhook blocking polling)
+    ```
+    - **Fix (Dec 4, 2025):**
+    ```bash
+    # Delete Telegram webhook
+    curl -s "https://api.telegram.org/bot{TOKEN}/deleteWebhook"
+    # Response: {"ok": true, "result": true, "description": "Webhook was deleted"}
+    
+    # Restart Python bot
+    docker restart telegram-trade-bot
+    
+    # Verify webhook removed
+    curl -s "https://api.telegram.org/bot{TOKEN}/getWebhookInfo"
+    # Shows: "url": "" (empty = polling can work)
+    ```
+    - **Impact:** Python bot now receives all messages via polling, `/status` works correctly
+    - **Architecture decision:** Cannot run both n8n webhook AND Python polling bot simultaneously
+    - **Options going forward:**
+      * **Option A (CURRENT):** Python bot with polling - handles `/status`, manual trades, position queries
+      * **Option B:** n8n webhook only - disable Python bot, handle commands in n8n workflows
+    - **Lesson:** Telegram API architecture restriction - must choose polling OR webhook, cannot have both
+    - **Prevention:** If n8n needs Telegram integration in future, either:
+      1. Disable Python bot first, OR
+      2. Use Python bot only, don't set Telegram webhooks in n8n
+    - **Git commit:** N/A (configuration fix, no code changes)
+    - **Status:** ✅ Fixed and verified working (user confirmed `/status` responds correctly)
+
 ## File Conventions
 
 - **API routes:** `app/api/[feature]/[action]/route.ts` (Next.js 15 App Router)