init: surfaces-bot — Telegram & Matrix prototype

- Surface Protocol: unified IncomingMessage/OutgoingUI/ChatContext
- Telegram: Forum Topics (group + topics per chat)
- Matrix: Space + rooms per chat
- MockPlatformClient with PlatformClient Protocol
- docs: surface-protocol, telegram/matrix specs, api-contract, claude-code-guide
- project scaffold: src/, tests/, pyproject.toml

Co-Authored-By: Claude Sonnet 4-6 <noreply@anthropic.com>

docs/telegram-prototype.md

@@ -0,0 +1,221 @@
+# Telegram — описание прототипа
+
+## Концепция
+
+Один бот, несколько чатов через Topics в Forum-группе.
+
+При первом запуске бот создаёт для пользователя персональную Forum-группу
+(супергруппу с включёнными темами). Каждый новый чат с агентом — отдельная тема
+внутри группы. Пользователь видит это как список чатов в одном месте.
+
+Бот управляет группой от имени пользователя через Telegram Bot API:
+создаёт темы, переименовывает, архивирует.
+
+---
+
+## Аутентификация
+
+### Флоу
+1. Пользователь пишет боту `/start`
+2. Бот проверяет — есть ли аккаунт на платформе привязанный к этому `tg_user_id`
+3. Если нет — бот отправляет одноразовую ссылку или код для входа
+4. Пользователь подтверждает, платформа возвращает токен сессии
+5. Бот сохраняет привязку `tg_user_id → platform_user_id`
+
+### В моке
+- Любой пользователь проходит аутентификацию автоматически
+- Кнопка «Войти» → пауза 1 сек → «Вы вошли как {имя}»
+- Демонстрирует флоу без реальной платформы
+
+---
+
+## Чаты через Forum Topics (вариант В)
+
+### Как это работает
+- Бот создаёт супергруппу с Topics для каждого нового пользователя
+- Каждый чат = отдельная тема (Topic) в этой группе
+- История хранится нативно в Telegram (в самой теме)
+- Переключение между чатами = переключение между темами
+
+### Управление чатами
+Внутри каждой темы доступны команды:
+
+| Команда | Действие |
+|---|---|
+| `/new` | Создать новый чат (новую тему) |
+| `/rename Название` | Переименовать текущий чат |
+| `/archive` | Архивировать текущий чат |
+| `/chats` | Показать список всех чатов |
+
+### Создание нового чата
+1. Пользователь пишет `/new` или нажимает кнопку
+2. Бот спрашивает название (опционально, можно пропустить)
+3. Бот создаёт новую тему в группе: «Чат 1», «Чат 2» и т.д.
+4. Бот отправляет в новую тему приветствие и создаёт сессию на платформе
+
+### В моке
+- Группа и темы создаются реально через Bot API
+- Сессии на платформе — через MockPlatformClient
+- История в темах хранится нативно в Telegram, ничего не нужно делать
+
+---
+
+## Основной диалог
+
+### Флоу сообщения
+1. Пользователь пишет текст в тему
+2. Бот показывает `typing...`
+3. Запрос уходит в платформу (сейчас — MockPlatformClient)
+4. Бот отвечает текстом агента
+
+### Вложения
+- Фото, документы, голосовые — передаются в платформу как `attachments`
+- В моке: бот подтверждает получение файла и возвращает заглушку-ответ
+- Форматы: PDF, изображения, текстовые файлы
+
+### Подтверждение действий
+Если агент собирается выполнить потенциально опасное действие
+(отправить письмо, удалить файл, сделать запись в календарь):
+
+```
+Агент хочет выполнить действие:
+📧 Отправить письмо на vasya@mail.ru
+Тема: «Отчёт за неделю»
+
+[✅ Подтвердить]  [❌ Отменить]
+```
+
+Пользователь нажимает кнопку — действие выполняется или отменяется.
+В моке: кнопки работают, действие логируется, ответ-заглушка.
+
+---
+
+## Настройки
+
+Доступны через `/settings` в любой теме или в главном меню бота.
+Реализованы как цепочка инлайн-кнопок.
+
+### Главное меню настроек
+```
+⚙️ Настройки
+
+[🔗 Коннекторы]   [🧩 Скиллы]
+[🧠 Личность]     [🔔 Уведомления]
+[🔒 Безопасность] [💳 Подписка]
+```
+
+### Коннекторы
+Подключение внешних сервисов. Агент получает доступ через API Proxy,
+пароли пользователю вводить не нужно — только OAuth.
+
+| Коннектор | Способ подключения |
+|---|---|
+| Gmail / Outlook | OAuth ссылка |
+| Google Calendar | OAuth ссылка |
+| GitHub | OAuth ссылка |
+| Notion | OAuth ссылка |
+| Telegram (читать каналы) | Уже подключён |
+
+В моке: кнопка «Подключить» → ссылка-заглушка → «Подключено ✓»
+
+### Скиллы
+Включение/выключение навыков агента.
+
+```
+🧩 Скиллы
+
+✅ Поиск в интернете
+✅ Чтение почты
+❌ Управление браузером
+❌ Генерация изображений
+❌ Работа с календарём
+✅ Работа с файлами
+❌ Генерация видео
+```
+
+Каждый скилл — кнопка-переключатель. Нажал — включил/выключил.
+В моке: состояние хранится локально, платформа не вызывается.
+
+### Личность агента (SOUL.md)
+Онбординг-анкета при первом входе, потом редактирование.
+
+```
+🧠 Личность агента
+
+Как зовут твоего агента?
+[_Лямбда_____________]
+
+Что он должен делать в первую очередь?
+[_Разбирать почту_____]
+
+Стиль общения:
+[Деловой] [Дружелюбный] [Краткий]
+```
+
+В моке: данные сохраняются, агент обращается к пользователю по имени из настроек.
+
+### Уведомления
+Когда агент выполнил долгую задачу — уведомление в Telegram.
+
+```
+🔔 Уведомления
+
+✅ Задача выполнена
+✅ Требуется подтверждение действия
+❌ Ежедневный дайджест
+❌ Напоминания из календаря
+```
+
+В моке: уведомления отправляются через бот с задержкой (симуляция).
+
+### Безопасность
+Какие действия требуют явного подтверждения.
+
+```
+🔒 Безопасность
+
+Всегда спрашивать перед:
+✅ Отправкой письма
+✅ Удалением файлов
+✅ Публикацией в соцсетях
+❌ Созданием события в календаре
+❌ Поиском в интернете
+```
+
+### Подписка
+Заглушка — реализует другая команда.
+
+```
+💳 Подписка
+
+Текущий план: Beta (бесплатно)
+Токены: ████████░░ 800/1000
+
+[Подробнее о планах]
+```
+
+---
+
+## FSM состояния
+
+```
+[Start] → AuthPending → AuthConfirmed
+                              ↓
+                         GroupSetup → Idle
+                                        ↓
+                              ReceivingMessage → WaitingResponse → Idle
+                                        ↓
+                              ConfirmAction → [Confirmed/Cancelled] → Idle
+                                        ↓
+                              Settings → [подменю] → Idle
+```
+
+---
+
+## Стек
+
+- Python 3.11+
+- aiogram 3.x (Router, FSM, InlineKeyboard, Forum Topics API)
+- MockPlatformClient → `platform/interface.py`
+- structlog для логирования
+- SQLite для хранения `tg_user_id → platform_user_id` и состояния скиллов