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>

CLAUDE.md

@@ -0,0 +1,172 @@
+# Surfaces team — Lambda Lab 3.0
+
+Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda.
+
+## Правило №1: не быть ждуном
+
+Платформа (SDK от Азамата) ещё не готова. Это **не блокер**.
+
+- Все вызовы платформы — через `platform/interface.py` (Protocol)
+- Реализация сейчас — `platform/mock.py` (MockPlatformClient)
+- При подключении реального SDK — меняем только `platform/mock.py`
+- Архитектурные решения принимаем сами, фиксируем в `docs/api-contract.md`
+
+---
+
+## Архитектура
+
+```
+surfaces-bot/
+  core/
+    protocol.py      — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
+    handler.py       — ядро: IncomingEvent → OutgoingEvent (общее для всех ботов)
+    session.py       — управление сессиями и чатами
+    auth.py          — AuthFlow
+    settings.py      — SettingsAction
+
+  adapter/
+    telegram/        — aiogram адаптер
+      converter.py   — aiogram Event → IncomingEvent и обратно
+      bot.py         — точка входа
+      handlers/      — aiogram роутеры
+      keyboards/     — инлайн-клавиатуры
+      states.py      — FSM состояния
+    matrix/          — matrix-nio адаптер
+      converter.py   — matrix-nio Event → IncomingEvent и обратно
+      bot.py         — точка входа
+      handlers/      — обработчики событий
+
+  platform/
+    interface.py     — Protocol: PlatformClient (контракт к SDK)
+    mock.py          — MockPlatformClient (заглушка)
+
+  docs/              — вся документация
+  tests/             — pytest тесты
+  .claude/agents/    — конфиги агентов
+```
+
+Подробно об унификации: `docs/surface-protocol.md`
+Telegram функционал: `docs/telegram-prototype.md`
+Matrix функционал: `docs/matrix-prototype.md`
+
+---
+
+## Агенты
+
+| Агент | Когда запускать | Модель | Токены |
+|-------|----------------|--------|--------|
+| `@researcher` | Изучить API, найти примеры | Haiku | ~дёшево |
+| `@architect` | Спроектировать решение | Sonnet | ~средне |
+| `@tg-developer` | Писать код Telegram-адаптера | Sonnet | ~средне |
+| `@matrix-developer` | Писать код Matrix-адаптера | Sonnet | ~средне |
+| `@core-developer` | Писать core/ и platform/ | Sonnet | ~средне |
+| `@reviewer` | Проверить код перед PR | Sonnet | ~средне |
+
+**Важно (Pro-лимиты):** не запускай больше двух Sonnet-агентов одновременно.
+Haiku можно запускать параллельно сколько угодно.
+
+---
+
+## Стратегия параллельной разработки
+
+Два бота разрабатываются параллельно, но через общее ядро.
+
+### Порядок работы
+
+```
+1. core/ — сначала (однократно, все ждут)
+   @core-developer пишет protocol.py, handler.py, session.py, auth.py, settings.py
+
+2. platform/ — сразу после core/
+   @core-developer пишет interface.py и mock.py
+
+3. adapter/telegram/ и adapter/matrix/ — параллельно
+   @tg-developer  →  adapter/telegram/
+   @matrix-developer  →  adapter/matrix/
+   Не пересекаются по файлам — можно одновременно в разных терминалах.
+```
+
+### Что можно делать одновременно (разные терминалы)
+
+```bash
+# Терминал 1 — Telegram адаптер
+claude "Use @tg-developer to implement adapter/telegram/handlers/start.py"
+
+# Терминал 2 — Matrix адаптер (параллельно)
+claude "Use @matrix-developer to implement adapter/matrix/handlers/start.py"
+```
+
+### Что нельзя делать одновременно
+
+- Два агента в одном файле
+- @core-developer параллельно с @tg-developer или @matrix-developer
+  (core/ должен быть готов до адаптеров)
+- Больше двух Sonnet-агентов одновременно (Pro-лимит)
+
+---
+
+## Git worktree workflow
+
+Каждая фича в отдельном worktree — адаптеры не мешают друг другу:
+
+```bash
+# Создать worktrees для параллельной работы
+git worktree add .worktrees/telegram -b feat/telegram-adapter
+git worktree add .worktrees/matrix   -b feat/matrix-adapter
+
+# Работать в каждом независимо
+cd .worktrees/telegram && claude "Use @tg-developer to ..."
+cd .worktrees/matrix   && claude "Use @matrix-developer to ..."
+
+# Смержить когда готово
+git checkout main
+git merge feat/telegram-adapter
+git merge feat/matrix-adapter
+```
+
+---
+
+## Команды запуска
+
+```bash
+# Установить зависимости
+uv sync
+
+# Запустить тесты
+pytest tests/ -v
+
+# Запустить только тесты Telegram
+pytest tests/adapter/telegram/ -v
+
+# Запустить только тесты Matrix
+pytest tests/adapter/matrix/ -v
+
+# Запустить только тесты ядра
+pytest tests/core/ -v
+
+# Запустить Telegram бота
+python -m adapter.telegram.bot
+
+# Запустить Matrix бота
+python -m adapter.matrix.bot
+```
+
+---
+
+## Переменные окружения
+
+```bash
+cp .env.example .env
+```
+
+Никогда не коммить `.env`.
+
+---
+
+## Экономия токенов (Pro-лимиты)
+
+- Исследования → всегда `@researcher` (Haiku), не Sonnet
+- Точечные правки в одном файле → напрямую без агента
+- Ревью → только перед PR, не после каждого коммита
+- Длинный контекст → дай агенту конкретный файл, не весь проект
+- Если агент "завис" в рассуждениях → прерви, переформулируй задачу точнее