feat(matrix): land QA follow-ups and refresh docs

- harden Matrix onboarding/chat lifecycle after manual QA
- refresh README and Matrix docs to match current behavior
- add local ignores for runtime artifacts and include current planning/report docs

Closes #7
Closes #9
Closes #14

docs/reports/2026-04-01-surfaces-progress-report.md

@@ -0,0 +1,601 @@
+# Отчёт о проделанной работе
+
+**Проект:** Lambda Lab 3.0 — Surfaces  
+**Команда:** Surfaces Team  
+**Дата:** 2026-04-01  
+**Период отчёта:** текущий этап разработки прототипов Telegram и Matrix  
+
+---
+
+## 1. Цель этапа
+
+Целью текущего этапа было собрать работоспособный прототип двух поверхностей для взаимодействия пользователя с AI-агентом Lambda:
+
+- Telegram-бота
+- Matrix-бота
+
+При этом важным требованием было не ждать готовности платформенного SDK, а сразу строить систему вокруг собственного контракта и мок-реализации платформы. Это позволило параллельно двигаться по UX, архитектуре и интеграционным сценариям, не блокируясь внешними зависимостями.
+
+---
+
+## 2. Что было сделано на уровне архитектуры
+
+### 2.1. Сформировано общее ядро
+
+В репозитории выделено общее `core/`, которое не зависит от конкретного транспорта и используется обеими поверхностями.
+
+Реализованы:
+
+- единый протокол событий и ответов
+- диспетчеризация входящих событий через `EventDispatcher`
+- менеджмент чатов
+- менеджмент аутентификации
+- менеджмент настроек
+- общее state-хранилище (`InMemoryStore`, `SQLiteStore`)
+
+Это позволило построить Telegram и Matrix как тонкие адаптеры, которые:
+
+- принимают события транспорта
+- конвертируют их в единый формат ядра
+- передают в `core`
+- рендерят результат обратно в транспорт
+
+### 2.2. Зафиксирован платформенный контракт
+
+Вместо ожидания готового SDK был введён собственный контракт через:
+
+- [`sdk/interface.py`](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/interface.py)
+- [`sdk/mock.py`](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/mock.py)
+
+За счёт этого:
+
+- UX и интеграционный слой можно развивать уже сейчас
+- реальные платформенные вызовы можно позже подключить заменой одной реализации
+- транспортные адаптеры и `core` не придётся переписывать
+
+### 2.3. Уточнена текущая архитектурная стратегия
+
+По ходу работы часть исходных планов была пересмотрена и адаптирована под реальные ограничения платформ и API.
+
+Ключевые изменения:
+
+- `platform/` был переименован в `sdk/` для устранения конфликта имён и более точного смысла слоя
+- Telegram ушёл от идеи автоматического создания групп ботом: Bot API этого не позволяет
+- Matrix ушёл от Space-first реализации к DM-first / room-first модели как к более реалистичному первому рабочему этапу
+
+---
+
+## 3. Telegram: текущее состояние
+
+### 3.1. Организация разработки
+
+Telegram-часть выделена в отдельный worktree:
+
+- ветка: `feat/telegram-adapter`
+
+Это позволило вести Telegram независимо от Matrix и не смешивать контексты разработки.
+
+### 3.2. Что реализовано
+
+В Telegram-адаптере уже собран рабочий базовый UX:
+
+- стартовый onboarding через `/start`
+- основной диалог в DM
+- создание новых чатов
+- список чатов и переключение между ними
+- меню настроек
+- подтверждение действий через inline-кнопки
+- базовая работа с вложениями
+
+Отдельно реализован **Forum Topics mode** как расширение поверх DM-сценария:
+
+- команда `/forum`
+- подключение уже существующей forum-group через пересланное сообщение
+- проверка, что бот является администратором с правом управления темами
+- синхронизация существующих локальных чатов с forum topics
+- routing сообщений из topic обратно в нужный chat context
+- routing confirm callbacks внутри topic
+
+### 3.3. Принятые продуктовые решения
+
+Во время разработки были приняты важные решения по UX Telegram:
+
+- основным пользовательским сценарием остаётся DM-first
+- Forum Topics не являются обязательным режимом, а выступают как advanced mode
+- контекст чатов должен синхронизироваться между DM и topic-представлением
+- пользователь не должен сталкиваться с невозможной автоматизацией создания групп со стороны бота
+
+### 3.4. Что ещё не закрыто
+
+Для Telegram остаются открытые задачи, в первую очередь в области polish и согласованности UX:
+
+- не все сценарии forum synchronization доведены до конца
+- есть оставшиеся вопросы по командам в topic-контексте
+- нужен дополнительный проход по UX-деталям и ручному QA
+
+Актуальный follow-up зафиксирован в issue:
+
+- `#15` Telegram forum topics: remaining UX and synchronization gaps
+
+---
+
+## 4. Matrix: текущее состояние
+
+### 4.1. Что реализовано
+
+В `main` уже добавлен Matrix-адаптер, включающий:
+
+- Matrix bot entrypoint
+- converter layer
+- room metadata store
+- routing входящих событий
+- обработку реакций
+- обработку приглашения в DM
+- базовый onboarding
+- platform-aware command hints
+- набор adapter-level тестов
+
+### 4.2. Главный архитектурный сдвиг
+
+Изначально Matrix рассматривался через модель:
+
+- персональный Space
+- settings-room
+- отдельные room-чаты внутри Space
+
+Однако по ходу реализации был выбран более прагматичный маршрут первого этапа:
+
+- **DM-first onboarding**
+- затем **room-per-chat**
+
+Текущее поведение:
+
+- пользователь приглашает бота в комнату
+- бот приветствует пользователя
+- первый контекст привязывается к `C1`
+- команда `!new` создаёт **реальную новую Matrix room**
+- бот приглашает пользователя в эту новую комнату
+
+Это уже соответствует целевому принципу:
+
+> новый чат пользователя должен быть отдельной сущностью транспорта, а не только внутренней записью в `core`
+
+### 4.3. Критические баги, которые были обнаружены и исправлены
+
+Во время ручной проверки Matrix были найдены и устранены несколько важных проблем:
+
+1. **бот не принимал invite корректно**
+   - причина: подписка только на `RoomMemberEvent`
+   - исправление: добавлена поддержка `InviteMemberEvent`
+
+2. **бот отвечал сам себе и уходил в цикл**
+   - симптом: спам приветствиями и сообщениями типа `Введите !start`
+   - причина: отсутствие фильтра собственных сообщений
+   - исправление: события от `self.client.user_id` теперь игнорируются
+
+3. **дублировалось стартовое приветствие**
+   - причина: invite-flow был неидемпотентным
+   - исправление: room onboarding сделан идемпотентным
+
+4. **слишком агрессивные timeout/retry при sync**
+   - исправление: настроен более мягкий transport config через `AsyncClientConfig`
+
+5. **команды и подсказки были Telegram-ориентированными**
+   - исправление: тексты в ядре стали platform-aware (`/start` для Telegram, `!start` для Matrix)
+
+### 4.4. Что подтверждено тестами
+
+Для Matrix собран и пройден набор тестов:
+
+- converter tests
+- dispatcher tests
+- reactions tests
+- store tests
+- интеграционные тесты core-сценариев
+
+Примеры покрытых сценариев:
+
+- разбор команд `!new`, `!skills`, `!yes`, `!no`
+- invite onboarding
+- защита от self-loop
+- создание реальной Matrix room на `!new`
+- mapping `room_id -> chat_id`
+
+### 4.5. Ограничение текущей реализации
+
+Главное незакрытое ограничение Matrix на текущий момент:
+
+## encrypted DM пока не поддержан
+
+Причина не в логике бота, а во внешнем crypto-stack:
+
+- для E2EE в `matrix-nio` нужен `python-olm`
+- на текущей macOS/ARM среде сборка `python-olm` не воспроизводится корректно
+- поэтому в рабочем сценарии Matrix пока используется **только незашифрованный room flow**
+
+Это означает:
+
+- незашифрованные комнаты и room-per-chat можно развивать и тестировать уже сейчас
+- encrypted DM нужно рассматривать как отдельную инфраструктурную подзадачу
+
+### 4.6. Что ещё остаётся по Matrix
+
+Открытые направления:
+
+- ручной QA текущего Matrix-бота
+- доработка UX и edge-cases room-per-chat
+- дальнейшее развитие settings-команд
+- возможное возвращение к Space lifecycle как следующему этапу
+- отдельный infrastructure task по E2EE / `python-olm`
+
+Для ручного тестирования создан issue:
+
+- `#14` Manual QA: test Matrix bot and record issues / gaps
+
+---
+
+## 5. Что было сделано с точки зрения git и процесса
+
+### 5.1. Основные изменения были оформлены коммитами
+
+На текущем этапе были сделаны и запушены в репозиторий следующие ключевые коммиты:
+
+- `82eb711` — базовый Matrix adapter + platform-aware command hints
+- `14c091b` — реальное создание новых Matrix rooms на `!new`
+- `6a843e8` — transport timeout tuning для Matrix sync
+- `27f3da8` — обновление README под фактическую архитектуру проекта
+
+### 5.2. Проведён аудит backlog
+
+По открытым issue был выполнен аудит:
+
+- закрыты уже выполненные задачи
+- устаревшие issue переписаны под текущую архитектуру
+- не выполненные и актуальные задачи оставлены открытыми
+
+В частности:
+
+- закрыт issue `#13` по Matrix research
+- актуализированы старые Telegram и Matrix issue под текущие реальные пути, ограничения и UX-модель
+
+---
+
+## 6. Что изменилось по сравнению с изначальным планом
+
+Это важный блок для руководителя: проект движется не просто по “чеклисту задач”, а по реальным ограничениям платформ.
+
+### 6.1. Telegram
+
+Изначально планировался сценарий, где бот создаёт Forum-группу сам.
+
+Фактический результат исследования и реализации показал:
+
+- Telegram Bot API этого не позволяет
+- группа создаётся пользователем вручную
+- бот подключается к уже существующей группе
+
+Это не регресс, а корректная адаптация архитектуры под реальные ограничения API.
+
+### 6.2. Matrix
+
+Изначально планировался Space-first UX.
+
+Фактически первым рабочим этапом стала модель:
+
+- DM-first onboarding
+- затем room-per-chat
+
+Причина:
+
+- так можно получить работающий transport flow раньше
+- это проще в отладке
+- это не блокирует дальнейший переход к Space lifecycle
+
+### 6.3. Платформенный слой
+
+Изначально существовали старые пути и слои, которые затем были пересобраны в более понятную форму.
+
+Итоговое направление:
+
+- `sdk/interface.py`
+- `sdk/mock.py`
+- `core/` как единый уровень бизнес-логики
+- transport adapters отдельно
+
+Это повысило устойчивость архитектуры и упростило дальнейшую замену mock на реальный SDK.
+
+---
+
+## 7. Основные результаты этапа
+
+К концу текущего этапа проект достиг следующих результатов:
+
+### Telegram
+
+- есть рабочий Telegram adapter
+- реализован основной DM flow
+- реализован Forum Topics mode
+- собрана отдельная ветка/worktree под Telegram
+- основные пользовательские сценарии уже можно проверять руками
+
+### Matrix
+
+- есть рабочий Matrix adapter
+- invite/onboarding flow уже функционирует
+- реализована модель room-per-chat
+- устранены основные критические баги цикла и self-processing
+- собран базовый test suite
+
+### Общий уровень проекта
+
+- ядро и контракты унифицированы
+- backlog приведён в соответствие с реальной архитектурой
+- README актуализирован под текущее состояние
+- ручной QA Matrix вынесен в отдельную управляемую задачу
+
+---
+
+## 8. Текущие риски и ограничения
+
+### Технические риски
+
+1. **Matrix E2EE**
+   - blocked внешним crypto-stack
+   - не решается только правками Python-кода в проекте
+
+2. **Telegram forum synchronization**
+   - функциональность уже есть, но остаются edge-cases и UX-недоработки
+
+3. **Расхождение старых документов и новых решений**
+   - backlog уже частично синхронизирован
+   - но часть старых design assumptions всё ещё может встречаться в документации
+
+### Процессные риски
+
+1. требуется более строгий feature-branch workflow для следующих этапов Matrix
+2. для Telegram и Matrix желательно продолжать раздельную работу по веткам/worktree
+3. ручной QA остаётся критичным, особенно для Matrix transport behavior
+
+---
+
+## 9. Следующие шаги
+
+### Ближайшие
+
+1. Провести ручной QA Matrix-бота по issue `#14`
+2. Зафиксировать воспроизводимые проблемы Matrix
+3. Продолжить Telegram в worktree `feat/telegram-adapter`
+4. Довести Telegram forum synchronization gaps по issue `#15`
+
+### Среднесрочные
+
+1. Расширить покрытие тестами
+2. Довести Matrix settings workflow
+3. Уточнить и обновить `docs/api-contract.md`
+4. Отдельно решить вопрос Matrix E2EE support
+
+### Стратегические
+
+1. Подготовить замену `MockPlatformClient` на реальный SDK
+2. Довести обе поверхности до более стабильного demo-ready состояния
+3. Выровнять UX Telegram и Matrix вокруг общих принципов surface protocol
+
+---
+
+## 10. Краткий вывод для руководителя
+
+На текущем этапе команда не просто написала часть кода, а уже собрала работающий каркас двух поверхностей вокруг общего ядра и собственного платформенного контракта.
+
+Главный практический результат:
+
+- Telegram уже находится в стадии реального UX-прототипа
+- Matrix уже имеет рабочий transport-слой и модель отдельных комнат для чатов
+- архитектура проекта стала значительно устойчивее и ближе к реальной интеграции с платформой
+
+При этом команда корректно адаптировала исходные планы под реальные ограничения Telegram Bot API и Matrix ecosystem, не пытаясь “продавить” заведомо неверные решения.
+
+То есть проект движется не по формальному чеклисту, а по зрелой инженерной логике:
+
+- исследование
+- фиксация архитектурных решений
+- рабочая реализация
+- ручной QA
+- корректировка backlog под фактическое состояние системы
+
+Это хороший признак для дальнейшего перехода от прототипа к более устойчивой демонстрационной версии.
+
+
+## 8. Дополнение: итоги отдельной Telegram-сессии по Forum Topics
+
+В рамках отдельной рабочей сессии в Telegram worktree `feat/telegram-adapter` был проведён focused pass по качеству и устойчивости **Forum Topics mode**. Целью этой работы было не просто добавить функциональность, а довести forum-сценарии до состояния, в котором их можно стабильно демонстрировать, вручную тестировать и развивать дальше без постоянных расхождений между UX, кодом и документацией.
+
+### 8.1. Что было выявлено в начале сессии
+
+При аудите Telegram-ветки подтвердилось, что базовая реализация уже существует:
+
+- Telegram adapter реализован
+- Forum Topics mode уже добавлен
+- `/forum` onboarding присутствует
+- forum thread routing реализован
+- confirm callbacks внутри forum thread уже работают
+
+Однако вместе с этим были обнаружены существенные проблемы двух типов.
+
+**Первый тип — расхождение документации и фактической реализации.**
+Часть документов всё ещё описывала старую DM-only или forum-only модель, тогда как код фактически уже работал как hybrid `DM + Forum Topics`.
+
+**Второй тип — реальные поведенческие баги forum mode.**
+Наиболее заметные проблемы:
+
+- нестабильный onboarding подключения forum group
+- слабая диагностика ошибок подключения
+- возможность сломать соответствие `topic -> chat` через команды управления чатами внутри topic
+- неполная согласованность UX внутри forum topics
+
+### 8.2. Исправление документации
+
+Были актуализированы Telegram-документы, чтобы они соответствовали реальному состоянию ветки:
+
+- `docs/telegram-prototype.md`
+- `docs/superpowers/specs/2026-03-31-telegram-adapter-design.md`
+
+Что было отражено в документации:
+
+- Telegram работает как hybrid-модель `DM + Forum Topics`
+- DM остаётся базовой поверхностью
+- Forum Topics — расширенный режим поверх того же chat context
+- `/forum` подключает уже существующую forum-group пользователя
+- один и тот же `chat_id` может быть доступен как из DM, так и из forum topic
+- forum thread routing и confirm callbacks уже входят в реализованную модель адаптера
+
+Практический результат: документация перестала вводить в заблуждение разработчиков и reviewers и теперь описывает не гипотетическую, а фактическую архитектуру Telegram-ветки.
+
+### 8.3. Разбор и исправление проблемного onboarding `/forum`
+
+Изначально `/forum` опирался на пересланное сообщение из супергруппы и ожидал, что Telegram отдаст боту `forward_from_chat`.
+
+В реальном запуске было установлено, что этот сценарий ненадёжен:
+
+- Telegram/aiogram может присылать не `forward_from_chat`, а `forward_origin`
+- в ряде случаев бот видит только `forward_origin_type=user`
+- из такого payload невозможно надёжно восстановить `group_id`
+
+То есть даже при визуально «правильной» пересылке сообщение не обязательно содержит необходимые данные о группе.
+
+Для диагностики в onboarding были добавлены stage-level логи. Теперь логируются:
+
+- запуск `/forum`
+- получение onboarding message
+- тип forward metadata
+- наличие или отсутствие данных о группе
+- тип найденного chat
+- проверка forum-enabled supergroup
+- права бота (`administrator` / `can_manage_topics`)
+- успешная привязка forum group
+- создание и привязка topics
+- завершение onboarding
+
+Это позволило быстро локализовать проблему и убедиться, что узкое место было именно в механике получения `group_id`.
+
+### 8.4. Перевод onboarding на Telegram-native `request_chat`
+
+Вместо ненадёжного forwarding-only flow основной путь подключения forum group был переведён на **Telegram-native выбор чата** через `request_chat`.
+
+Было сделано следующее:
+
+- добавлена новая клавиатура выбора forum-group
+- `/forum` теперь предлагает пользователю выбрать подходящую group кнопкой
+- бот получает `chat_shared.chat_id` напрямую
+- после выбора выполняется проверка реальных прав бота в группе
+- старый forwarding path оставлен как fallback
+
+Это решение даёт несколько преимуществ:
+
+- не зависит от нестабильных forwarded metadata
+- даёт детерминированный `chat_id`
+- лучше соответствует реальному Telegram API
+- делает onboarding заметно понятнее для пользователя
+
+### 8.5. Исправление ошибки `USER_RIGHTS_MISSING`
+
+После внедрения `request_chat` на реальном запуске проявилась новая ошибка:
+
+- `TelegramBadRequest: USER_RIGHTS_MISSING`
+
+Ошибка возникала ещё на этапе отправки кнопки выбора forum-group.
+
+Причина: в `KeyboardButtonRequestChat` был указан слишком жёсткий набор `bot_administrator_rights`, из-за чего Telegram отклонял сам запрос на показ кнопки.
+
+Исправление:
+
+- из `request_chat` были убраны жёсткие `bot_administrator_rights`
+- фактическая проверка нужных прав оставлена на следующем шаге через `get_chat_member`
+
+В результате onboarding сохранил строгую проверку прав, но перестал ломаться на этапе отправки UI.
+
+### 8.6. Исправление опасного поведения внутри forum topics
+
+После успешного onboarding был отдельно проверен UX внутри уже созданных topics. Здесь обнаружился критичный баг: пользователь мог использовать `/chats` в topic-контексте и переключать активный чат через inline callbacks.
+
+Это приводило к рассинхронизации:
+
+- Telegram topic визуально оставался темой одного чата
+- FSM и routing переключались на другой чат
+- пользователь начинал фактически разговаривать «в чате 4 внутри темы чата 2»
+
+Чтобы устранить этот класс ошибок, были введены ограничения для topic-контекста.
+
+Теперь внутри forum topic:
+
+- `/chats` не открывает механизм переключения и сообщает, что эта функция доступна только в DM
+- callback `switch:<chat_id>:<name>` запрещён
+- callback `new_chat` из списка чатов запрещён
+
+Это устранило основной сценарий, которым пользователь мог руками сломать привязку `topic -> chat`.
+
+### 8.7. Что покрыто тестами
+
+В рамках этой же сессии были расширены Telegram-specific тесты. Покрыты сценарии:
+
+- forum routing helpers
+- `/forum` переводит FSM в setup state
+- подключение группы через `forward_from_chat`
+- подключение группы через `forward_origin`
+- подключение группы через `chat_shared`
+- негативные сценарии без метаданных группы
+- негативный сценарий для supergroup без Topics
+- routing сообщений в forum thread
+- создание forum topic при `/new` в DM
+- регистрация чата в текущем topic
+- confirm callback внутри forum thread
+- запрет `/chats` внутри topic
+- запрет `switch` callback внутри topic
+- запрет `new_chat` callback внутри topic
+
+Проверка выполнялась командами:
+
+- `pytest tests/adapter/telegram/test_forum.py -q`
+- `pytest tests/core/test_dispatcher.py tests/core/test_integration.py -q`
+
+Результат: ключевые улучшения forum mode закреплены тестами, а не остались только на уровне ручной отладки.
+
+### 8.8. Что ещё осталось как follow-up
+
+Во время сессии были зафиксированы проблемы, которые разумно вынести в отдельную follow-up задачу, а не смешивать с текущими исправлениями.
+
+Оставшиеся gap'ы:
+
+- глобальные команды Telegram всё ещё видны и в topic-контексте, хотя часть из них логически там отключена
+- `/new <name>` внутри уже связанного topic может переименовать локальный чат, но не переименовывает сам Telegram topic
+- callback `new_chat` из DM-списка пока не синхронизирован с forum topic creation так же, как `/new` в DM
+
+Эти пункты были вынесены в отдельный issue:
+
+- `#15` — `Telegram forum topics: remaining UX and synchronization gaps`
+
+### 8.9. Git-результат Telegram-сессии
+
+По итогам сессии изменения были оформлены отдельным коммитом и опубликованы в удалённую ветку.
+
+**Commit:**
+
+- `a1b7a14` — `Improve Telegram forum onboarding and topic safety`
+
+**Push:**
+
+- `origin/feat/telegram-adapter`
+
+### 8.10. Практический результат этой Telegram-сессии
+
+На выходе Telegram Forum Topics mode стал существенно устойчивее и пригоднее для демонстрации и дальнейшей разработки.
+
+Главные практические улучшения:
+
+- forum onboarding стал надёжнее за счёт `request_chat`
+- диагностика ошибок onboarding стала прозрачной
+- пользователю стало сложнее случайно сломать topic-context
+- документация приведена в соответствие с кодом
+- изменения закреплены тестами
+- остаточные проблемы не потеряны и вынесены в issue tracker
+
+Итог: Telegram forum mode из состояния «уже работает, но легко ломается и плохо диагностируется» был переведён в состояние «работает заметно устойчивее, ограничивает опасные сценарии и имеет понятный backlog дальнейших улучшений».