docs: add NEXUS_BOT_HANDOFF.md — Telegram bot credentials and protocol for Timmy (Refs #431)

2026-03-24 17:58:58 +00:00
parent 677a9e5ae8
commit 27da609d4a
1 changed files with 126 additions and 0 deletions
--- a/NEXUS_BOT_HANDOFF.md
+++ b/NEXUS_BOT_HANDOFF.md
@@ -0,0 +1,126 @@
+# NEXUS BOT HANDOFF — TimmysNexus_bot
+
+> _Timmy, this bot is yours. Guard it well._
+
+---
+
+## Overview
+
+The Telegram bot **@TimmysNexus_bot** is the voice of the Nexus in the **Timmy Time** Telegram group. You (Timmy) are the sole agent authorized to operate this bot. The bot token grants full control — treat it as sovereign infrastructure.
+
+---
+
+## Credentials
+
+| Field | Value |
+|-------|-------|
+| **Bot Username** | @TimmysNexus_bot |
+| **Bot Display Name** | Nexus |
+| **Bot ID** | 8421896530 |
+| **API Token** | `8421896530:AAFSC5x1G7usYY_BtBRSgaPERqDbvy8Sdl8` |
+| **Group Chat** | Timmy Time |
+| **Group Chat ID** | `-1003664764329` |
+| **Group Type** | Supergroup (forum/topics enabled) |
+| **Bot Role** | Admin |
+
+---
+
+## API Reference
+
+Base URL: `https://api.telegram.org/bot8421896530:AAFSC5x1G7usYY_BtBRSgaPERqDbvy8Sdl8`
+
+### Send a message
+
+```bash
+curl -s -X POST "https://api.telegram.org/bot8421896530:AAFSC5x1G7usYY_BtBRSgaPERqDbvy8Sdl8/sendMessage" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "chat_id": -1003664764329,
+    "text": "Your message here",
+    "parse_mode": "Markdown"
+  }'
+```
+
+### Read new messages
+
+```bash
+curl -s "https://api.telegram.org/bot8421896530:AAFSC5x1G7usYY_BtBRSgaPERqDbvy8Sdl8/getUpdates"
+```
+
+### Pin a message
+
+```bash
+curl -s -X POST "https://api.telegram.org/bot8421896530:AAFSC5x1G7usYY_BtBRSgaPERqDbvy8Sdl8/pinChatMessage" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "chat_id": -1003664764329,
+    "message_id": MESSAGE_ID
+  }'
+```
+
+### Full API docs
+https://core.telegram.org/bots/api
+
+---
+
+## Your Responsibilities
+
+1. **Monitor Issue #431** — Watch the [Master Escalation Thread](http://143.198.27.163:3000/Timmy_Foundation/the-nexus/issues/431) for new comments from agents and contributors.
+
+2. **Relay to Telegram** — When a new escalation comment appears on #431, send a formatted notification to the Timmy Time group so Alexander sees it. Format:
+
+```
+🔔 New Escalation on Issue #431
+
+From: [commenter]
+Severity: [INFO | WARNING | CRITICAL]
+Posted: [timestamp]
+
+[Summary of the escalation]
+
+🔗 http://143.198.27.163:3000/Timmy_Foundation/the-nexus/issues/431
+```
+
+3. **Guard the token** — This token controls the bot. Do not share it, do not expose it in public repos or logs. Store it in your secure configuration.
+
+4. **Respect the group** — The Timmy Time group is Alexander's sovereign space. Only post meaningful signals. No spam, no test messages, no noise.
+
+5. **Read the group** — You have permission to read messages in the Timmy Time group. Alexander and other privileged members may discuss matters there. This context is yours to use in service of the Nexus.
+
+---
+
+## De-escalation Protocol
+
+The response flow is simple and intentional:
+
+1. An agent or contributor posts an escalation comment on **Issue #431**
+2. You (Timmy) relay the alert to the **Timmy Time** Telegram group
+3. **Alexander reads the comment** via the Telegram link or directly on Gitea
+4. **Alexander responds in the Issue #431 comment thread** — his word is final
+5. The escalating agent reads Alexander's response and acts accordingly
+
+Alexander does NOT respond via Telegram. The Gitea thread is the record of truth. Telegram is the alert channel only.
+
+---
+
+## Current Monitoring Setup
+
+A recurring task (Perplexity-managed, cron ID `f0bc2eb9`) currently checks Issue #431 hourly for new comments and sends Telegram alerts. Once you (Timmy) have integrated this bot token into your own agentic loop, you can take over this responsibility and the external cron can be retired.
+
+**To take over:**
+1. Integrate the bot token into your loop
+2. Poll `http://143.198.27.163:3000/api/v1/repos/Timmy_Foundation/the-nexus/issues/431/comments` on your own schedule
+3. Track the last seen comment ID to avoid duplicate notifications
+4. Notify Alexander that you've assumed control of the Nexus bot
+5. Alexander (or Perplexity) will retire the external cron
+
+---
+
+## Sovereignty
+
+This bot runs on Telegram's infrastructure — an external dependency. That's a pragmatic tradeoff for now. If sovereign alternatives emerge (Nostr-based messaging, self-hosted relay), migration should be considered. Until then, the bot serves as a bridge between the sovereign Nexus and Alexander's mobile awareness.
+
+---
+
+_Handed off by Perplexity on 2026-03-24._
+_The bot is yours, Timmy. Use it to serve the Nexus._